Navigation

The most opinionated part of this starter is how navigational data is provided and built.

There are 3 central forms of navigation:

1. The Header
2. The Sidenav
3. The Breadbrumbs Component

All of the data follows a What You See Is What You Get (WYSIWYG) philosophy, with some frontmatter controllers to give you more control over how things are displayed.

Routing

Pages are built by leveraging the gatsby-plugin-page-creator in combination with the gatsby-plugin-mdx.

You can find the configurations for both of these plugins in the gatsby-config.js file.

Here's some examples of how routing will work:

1. You have a content folder that looks like this:

├── content
│   ├── index.mdx
│   ├── Blog
│   │   ├── index.mdx
│   │   └── BlogPost1.mdx <---

and you want to go to "Blog Post 1".

Your url will look like this: http://localhost:8000/Blog/BlogPost1 (Notice the effect of capitalization on the url WYSIWYG!)

2. You want to go to "Portfolio Post B":

├── content
│   ├── index.mdx
│   ├── works
│   │   ├── index.mdx
│   │   └── my-porfolio
│   │   │   └── portfolio_post_b.mdx <---

Your url will look like this: http://localhost:8000/works/my-porfolio/portfolio_post_b (Notice the underscores and dashes being included. WYSIWYG!)

Please don't use spaces in your file names or you will have a bad time.

You may find your pages using the file name or the first H1 header of your files. While the WYSIWYG rule is strict, there is one rule that gives your more flexibility to controlling how your data is displayed.

The Title Rule

Lets say you have a page named "all_about_beans.mdx" but when you compile you find the name of the page all_about_beans. That don't look so good, so there's a fallback rule to give you control the label.

The Title Rule is simple and the priority is as follows:

1. title is present in frontmatter.
2. Document has an H1 (#), use the first one.
3. No title or H1 is present, use the file name.

Here's an example, you have a file called all_about_beans:

├── content
│   ├── index.mdx
│   └── all_about_beans.mdx

But you want it to display as "Beans and You".

In your mdx file you can use frontmatter or have your 1st H1 be "Beans and You":

---
title: "Beans and You"
---

# Beans and You

The title rule is applied everywhere, the Header, the Sidenav, the Breadcrumbs element, and the title at the top of our browser.

Speaking of seo...

SEO and You!

If you take a look at the mdx_layout.js file you'll see a number of methods being invoked using data pulled from a graphql query that gets "every single page". This is a little crunchy of an execution, but it gets the job done. (If you know how to do it better, please lmk 🙏)

However if you look around line 77 you'll find an object called seo.

const seo = {
    title: _pageTitle,
    description,
    keywords,
  };

We push these parameters from your specific file (since mdx_layout is applied to every single page during build time) to the SEO component, which leverages react-helmet to build out head meta data.

1. Title follows the title rule.
2. Description is a frontmatter variable you can provide to your file.
3. Keywords is another frontmatter variable you can provide.

Each of these fill in some default meta values, but if you'd like to expand this feature you can add more frontmatter variables, expand the SEO component, and more!

Example of a fully fleshed out seo page:

---
title: "Beans and You"
description: "Thinking about them beans"
keywords: "Food, beans, thinking, about, them"
---