iSharkFly-Docs
/
packer-cn
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

website: update readme to reflect revised nav-data and plugin docs

This commit is contained in:
Zach Shilton 2021-03-18 12:26:03 -04:00
parent e68e736b6c
commit 9e03647ad7
No known key found for this signature in database
GPG Key ID: 487BAB946192712E
1 changed files with 169 additions and 63 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

232
website/README.md
View File

@ -238,14 +238,22 @@ $ terraform apply
<!-- END: editing-markdown -->
<!-- BEGIN: editing-docs-sidebars -->
<!-- Generated text, do not edit directly -->
<!--
NOTE: The "Editing Navigation Sidebars" section is forked from editing-docs-sidebars.
We plan on rolling these changes back into our "readme partials" source once all docs sites
have been transitioned to the JSON navigation format. See MKTG_032 for details:
https://docs.google.com/document/d/1kYvbyd6njHFSscoE1dtDNHQ3U8IzaMdcjOS0jg87rHg/
-->
## 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
.
@ -259,36 +267,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`:
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`:
```js
export default {
category: 'directory',
content: [
'file',
'another-file',
{
category: 'nested-directory',
content: ['nested-file'],
},
],
}
```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 `pages/<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
.
@ -297,36 +324,95 @@ 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.
<!-- END: editing-docs-sidebars -->
### Plugin Docs
Plugin documentation may be located within the `packer` repository, or split out into separate `packer-plugin-` repositories. For plugin docs within the `packer` repository, the process for authoring files and managing sidebar data is identical to the process for other documentation.
For plugins in separate repositories, additional configuration is required.
#### Setting up remote plugin docs
Some setup is required to include docs from remote plugin repositories on the [packer.io/docs](https://www.packer.io/docs) site.
1. The plugin repository needs to include a `docs.zip` asset in its release
2. The `packer` repository must have a corresponding entry in `website/data/docs-remote-plugins.json` which points to the plugin repository.
The `docs.zip` release asset is expected to be generated as part of the standard release process for `packer-plugin-*` repositories. Additional details on this process can be found in [the `packer-plugin-scaffolding` `README`](https://github.com/hashicorp/packer-plugin-scaffolding#registering-documentation-on-packerio).
The `docs-remote-plugins.json` file contains an array of entries. Each entry points to a plugin repository. The `{ title, path, repo, tag }` properties are required for each entry, all other properties are optional.
```json5
[
{
// ALL FIELDS ARE REQUIRED.
// "title" sets the human-readable title shown in navigation
title: 'Scaffolding',
// "path" sets the URL subpath under the component URL (eg `docs/builders`)
path: 'scaffolding',
// "repo" points to the plugin repo, in the format "organization/repo-name"
// if the organization == hashicorp, the plugin docs will be labelled "official".
// for all other organizations or users, plugin docs will be labelled "community".
repo: 'hashicorp/packer-plugin-scaffolding',
// "version" is used to fetch "docs.zip" from the matching tagged release.
// version: "latest" is permitted, but please be aware that it
// may fetch incompatible or unintended versions of plugin docs.
// if version is NOT "latest", and if "docs.zip" is unavailable, then
// we fall back to fetching docs from the source "{version}.zip"
version: 'v0.0.5',
},
]
```
#### Updating remote plugin docs
Documentation from plugin repositories is fetched and rendered every time the Packer website builds. So, to update plugin documentation on the live site:
1. In the plugin repository, publish a new release that includes a `docs.zip` release asset
2. In the `packer` repository, update `website/data/docs-remote-plugins.json` to ensure the corresponding entry points to the correct release `version` (which should correspond to the release's tag name). This may not be necessary if the `version` is set to `"latest"`.
3. Rebuild the website. This will happen automatically on commits to `stable-website`. In exceptional cases, the site can also be [manually re-deployed through Vercel](https://vercel.com/hashicorp/packer).
<!-- BEGIN: releases -->
<!-- Generated text, do not edit directly -->
@ -374,8 +460,18 @@ You may customize the parameters in any way you'd like. To remove a prerelease f
<!-- END: releases -->
<!-- BEGIN: redirects -->
<!-- Generated text, do not edit directly -->
<!--
NOTE: The "Redirects" section is forked from redirects.
There are minor changes related to sidebar navigation format changes.
We plan on rolling these changes back into our "readme partials" source once all docs sites
have been transitioned to the JSON navigation format. See MKTG_032 for details:
https://docs.google.com/document/d/1kYvbyd6njHFSscoE1dtDNHQ3U8IzaMdcjOS0jg87rHg/
-->
## Link Validation
@ -406,7 +502,7 @@ There are a couple important caveats with redirects. First, redirects are applie
Second, redirects do not apply to client-side navigation. By default, all links in the navigation and docs sidebar will navigate purely on the client side, which makes navigation through the docs significantly faster, especially for those with low-end devices and/or weak internet connections. In the future, we plan to convert all internal links within docs pages to behave this way as well. This means that if there is a link on this website to a given piece of content that has changed locations in some way, we need to also _directly change existing links to the content_. This way, if a user clicks a link that navigates on the client side, or if they hit the url directly and the page renders from the server side, either one will work perfectly.
Let's look at an example. Say you have a page called `/docs/foo` which needs to be moved to `/docs/nested/foo`. Additionally, this is a page that has been around for a while and we know there are links into `/docs/foo.html` left over from our previous website structure. First, we move the page, then adjust the docs sidenav, in `data/docs-navigation.js`. Find the category the page is in, and move it into the appropriate subcategory. Next, we add to `_redirects` as such:
Let's look at an example. Say you have a page called `/docs/foo` which needs to be moved to `/docs/nested/foo`. Additionally, this is a page that has been around for a while and we know there are links into `/docs/foo.html` left over from our previous website structure. First, we move the page, then adjust the docs sidenav, in `data/docs-nav-data.json`. Find the category the page is in, and move it into the appropriate subcategory. Next, we add to `_redirects` as such:
```
/foo /nested/foo 301!
@ -415,26 +511,36 @@ Let's look at an example. Say you have a page called `/docs/foo` which needs to
Finally, we run a global search for internal links to `/foo`, and make sure to adjust them to be `/nested/foo` - this is to ensure that client-side navigation still works correctly. _Adding a redirect alone is not enough_.
One more example - let's say that content is being moved to an external website. A common example is guides moving to `learn.hashicorp.com`. In this case, we take all the same steps, except that we need to make a different type of change to the `docs-navigation` file. If previously the structure looked like:
One more example - let's say that content is being moved to an external website. A common example is guides moving to `learn.hashicorp.com`. In this case, we take all the same steps, except that we need to make a different type of change to the `docs-nav-data` file. If previously the structure looked like:
```js
{
category: 'docs',
content: [
'foo'
]
}
```json
[
{
"name": "Docs",
"routes": [
{
"title": "Foo",
"path": "docs/foo"
}
]
}
]
```
If we no longer want the link to be in the side nav, we can simply remove it. If we do still want the link in the side nav, but pointing to an external destnation, we need to slightly change the structure as such:
If we no longer want the link to be in the side nav, we can simply remove it. If we do still want the link in the side nav, but pointing to an external destination, we need to slightly change the structure as such:
```js
{
category: 'docs',
content: [
{ title: 'Foo Title', href: 'https://learn.hashicorp.com/<product>/foo' }
]
}
```json
[
{
"name": "Docs",
"routes": [
{
"title": "Foo",
"href": "https://learn.hashicorp.com/<product>/foo"
}
]
}
]
```
As the majority of items in the side nav are internal links, the structure makes it as easy as possible to represent these links. This alternate syntax is the most concise manner than an external link can be represented. External links can be used anywhere within the docs sidenav.