Skip to content

Commit

Permalink
website: update readme (hashicorp#11421)
Browse files Browse the repository at this point in the history 
* website: bump to latest nextjs-scripts prerelease

* website: run generate:readme to update website readme blocks

* website: revert bump to nextjs-scripts, deferred
  • Loading branch information
@zchsh @jartek
zchsh authored and jartek committed Sep 11, 2021
1 parent 613d4ee commit ed612d1
Showing 1 changed file with 79 additions and 42 deletions.
121 changes: 79 additions & 42 deletions website/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -68,6 +68,8 @@ Documentation content is written in [Markdown](https://www.markdownguide.org/che

To create a new page with Markdown, create a file ending in `.mdx` in a `content/<subdirectory>`. The path in the content directory will be the URL route. For example, `content/docs/hello.mdx` will be served from the `/docs/hello` URL.

> **Important**: Files and directories will only be rendered and published to the website if they are [included in sidebar data](#editing-navigation-sidebars). Any file not included in sidebar data will not be rendered or published.
This file can be standard Markdown and also supports [YAML frontmatter](https://middlemanapp.com/basics/frontmatter/). YAML frontmatter is optional, there are defaults for all keys.

```yaml
Expand Down Expand Up @@ -124,6 +126,8 @@ The `Tabs` component creates tabbed content of any type, but is often used for c

![Tabs Component](https://p176.p0.n0.cdn.getcloudapp.com/items/WnubALZ4/Screen%20Recording%202020-06-11%20at%2006.03%20PM.gif?v=1de81ea720a8cc8ade83ca64fb0b9edd)

> Please refer to the [Swingset](https://react-components.vercel.app/?component=Tabs) documention for the latest examples and API reference.
It can be used as such within a markdown file:

````mdx
Expand Down Expand Up @@ -240,9 +244,9 @@ $ terraform apply

## Editing Navigation Sidebars

The structure of the sidebars are controlled by files in the [`/data` directory](data). For example, [this file](data/docs-navigation.js) controls the **docs** sidebar. Within the `data` folder, any file with `-navigation` after it controls the navigation for the given section.
The structure of the sidebars are controlled by files in the [`/data` directory](data). For example, [data/docs-nav-data.json](data/docs-nav-data.json) controls the **docs** sidebar. Within the `data` folder, any file with `-nav-data` after it controls the navigation for the given section.

The sidebar uses a simple recursive data structure to represent _files_ and _directories_. A file is represented by a string, and a directory is represented by an object. The sidebar is meant to reflect the structure of the docs within the filesystem while also allowing custom ordering. Let's look at an example. First, here's our example folder structure:
The sidebar uses a simple recursive data structure to represent _files_ and _directories_. The sidebar is meant to reflect the structure of the docs within the filesystem while also allowing custom ordering. Let's look at an example. First, here's our example folder structure:

```text
.
Expand All @@ -256,36 +260,55 @@ The sidebar uses a simple recursive data structure to represent _files_ and _dir
│   └── nested-file.mdx
```

Here's how this folder structure could be represented as a sidebar navigation, in this example it would be the file `website/data/docs-navigation.js`:

```js
export default {
category: 'directory',
content: [
'file',
'another-file',
{
category: 'nested-directory',
content: ['nested-file'],
},
],
}
Here's how this folder structure could be represented as a sidebar navigation, in this example it would be the file `website/data/docs-nav-data.json`:

```json
[
{
"title": "Directory",
"routes": [
{
"title": "Overview",
"path": "directory"
},
{
"title": "File",
"path": "directory/file"
},
{
"title": "Another File",
"path": "directory/another-file"
},
{
"title": "Nested Directory",
"routes": [
{
"title": "Overview",
"path": "directory/nested-directory"
},
{
"title": "Nested File",
"path": "directory/nested-directory/nested-file"
}
]
}
]
}
]
```

- `category` values will be **directory names** within the `content/<section>` directory
- `content` values will be **file names** within their appropriately nested directory

A couple more important notes:

- Within this data structure, ordering does not matter, but hierarchy does. So while you could put `file` and `another-file` in any order, or even leave one or both of them out, you could not decide to un-nest the `nested-directory` object without also un-nesting it in the filesystem.
- The `sidebar_title` frontmatter property on each `mdx` page is responsible for displaying the human-readable page name in the navigation.
- _By default_, every directory/category must have an `index.mdx` file. This file will be automatically added to the navigation as "Overview", and its `sidebar_title` property will set the human-readable name of the entire category.
- Within this data structure, ordering is flexible, but hierarchy is not. The structure of the sidebar must correspond to the structure of the content directory. So while you could put `file` and `another-file` in any order in the sidebar, or even leave one or both of them out, you could not decide to un-nest the `nested-directory` object without also un-nesting it in the filesystem.
- The `title` property on each node in the `nav-data` tree is the human-readable name in the navigation.
- The `path` property on each leaf node in the `nav-data` tree is the URL path where the `.mdx` document will be rendered, and the
- Note that "index" files must be explicitly added. These will be automatically resolved, so the `path` value should be, as above, `directory` rather than `directory/index`. A common convention is to set the `title` of an "index" node to be `"Overview"`.

Below we will discuss a couple of more unusual but still helpful patterns.

### Index-less Categories

Sometimes you may want to include a category but not have a need for an index page for the category. This can be accomplished, but a human-readable category name needs to be set manually, since the category name is normally pulled from the `sidebar_title` property of the index page. Here's an example of how an index-less category might look:
Sometimes you may want to include a category but not have a need for an index page for the category. This can be accomplished, but as with other branch and leaf nodes, a human-readable `title` needs to be set manually. Here's an example of how an index-less category might look:

```text
.
Expand All @@ -294,31 +317,45 @@ Sometimes you may want to include a category but not have a need for an index pa
│   └── file.mdx
```

```js
// website/data/docs-navigation.js
export default {
category: 'indexless-category',
name: 'Indexless Category',
content: ['file'],
}
```json
// website/data/docs-nav-data.json
[
{
"title": "Indexless Category",
"routes": [
{
"title": "File",
"path": "indexless-category/file"
}
]
}
]
```

The addition of the `name` property to a category object is all it takes to be able to skip the index file.

### Custom or External Links

Sometimes you may have a need to include a link that is not directly to a file within the docs hierarchy. This can also be supported using a different pattern. For example:

```js
export default {
category: 'directory',
content: [
'file',
'another-file',
{ title: 'Tao of HashiCorp', href: 'https://www.hashicorp.com/tao-of-hashicorp' }
}
]
}
```json
[
{
"name": "Directory",
"routes": [
{
"title": "File",
"path": "directory/file"
},
{
"title": "Another File",
"path": "directory/another-file"
},
{
"title": "Tao of HashiCorp",
"href": "https://www.hashicorp.com/tao-of-hashicorp"
}
]
}
]
```

If the link provided in the `href` property is external, it will display a small icon indicating this. If it's internal, it will appear the same way as any other direct file link.
Expand Down

0 comments on commit ed612d1

Please sign in to comment.