Content for Terraform's agents documentation.
If you find a typo or you feel like you can improve the HTML, CSS, or JavaScript, we welcome contributions. Feel free to open issues or pull requests like any normal GitHub project, and we'll merge it in ๐
The website reads content from release tags to generate documentation for all versions of terraform-docs-agents
documentation. Changes merged into main
will be included in the documentation for the next product release.
You cannot edit documentation for past versions of terraform-docs-agents
on the site. Documentation is an artifact of a product release. We push docs fixes forward for the next release, rather than retroactively fixing older versions.
You should preview your changes locally to ensure that the content is rendering properly before you create a pull request. The build includes content from this repository and the terraform-website
repository, allowing you to preview the entire Terraform documentation site.
To preview your content, complete the following steps:
Set Up Local Environment
- Install Docker.
- Restart your terminal or command line session.
Launch Site Locally
- Navigate into your local
terraform-docs-agents
top-level directory and runmake website
. - Open
http://localhost:3000
in your web browser. While the preview is running, you can edit pages and Next.js will automatically rebuild them. - When you're done with the preview, press
ctrl-C
in your terminal to stop the server.
The website reads content from release tags to generate documentation for all versions of terraform-docs-agents
documentation. Changes merged into main
are included in the documentation for the next product release.
You cannot edit documentation for past versions of terraform-docs-agents
on the site. Documentation is an artifact of a product release. We push docs fixes forward for the next release, rather than retroactively fixing older versions.
Documentation content is written in Markdown and you'll find all files listed under the /content
directory.
To create a new page with Markdown, create a file ending in .mdx
in a website/docs/<subdirectory>
. The path in the content directory will be the URL route. For example, website/docs/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. Any file not included in sidebar data will not be rendered or published.
This file can be standard Markdown and also supports YAML frontmatter. YAML frontmatter is optional, there are defaults for all keys.
---
title: "My Title"
description: "A thorough, yet succinct description of the page's contents"
---
The significant keys in the YAML frontmatter are:
title
(string)
- This is the title of the page that will be set in the HTML title.description
(string)
- This is a description of the page that will be set in the HTML description.
โ ๏ธ If there is a need for a/api/*
url on this website, the url will be changed to/api-docs/*
, as theapi
folder is reserved by next.js.
Content changes are automatically validated against a set of rules as part of the pull request process. If you want to run these checks locally to validate your content before committing your changes, you can run the following command:
npm run content-check
If the validation fails, actionable error messages will be displayed to help you address detected issues.
There is currently a small bug with new page creation - if you create a new page and link it up via subnav data while the server is running, it will report an error saying the page was not found. This can be resolved by restarting the server.
There are several custom markdown plugins that are available by default that enhance standard markdown to fit our use cases. This set of plugins introduces a couple instances of custom syntax, and a couple specific pitfalls that are not present by default with markdown, detailed below:
-
If you see the symbols
~>
,->
,=>
, or!>
, these represent custom alerts. These render as colored boxes to draw the user's attention to some type of aside. -
If you see
@include '/some/path.mdx'
, this is a markdown include. It's worth noting as well that all includes resolve fromwebsite/content/partials
by default, and that changes to partials will not live-reload the website. -
If you see
# Headline ((#slug))
, this is an example of an anchor link alias. It adds an extra permalink to a headline for compatibility and is removed from the output. -
Due to automatically generated permalinks, any text changes to headlines or list items that begin with inline code can and will break existing permalinks. Be very cautious when changing either of these two text items.
Headlines are fairly self-explanatory, but here's an example of how to list items that begin with inline code look.
- this is a normal list item - `this` is a list item that begins with inline code
Its worth noting that only the inline code at the beginning of the list item will cause problems if changed. So if you changed the above markup to...
- lsdhfhksdjf - `this` jsdhfkdsjhkdsfjh
...while it perhaps would not be an improved user experience, no links would break because of it. The best approach is to avoid changing headlines and inline code at the start of a list item. If you must change one of these items, make sure to tag someone from the digital marketing development team on your pull request, they will help to ensure as much compatibility as possible.
A number of custom mdx components are available for use within any .mdx file. If you have questions about custom components, or have a request for a new custom component, please reach out to @hashicorp/digital-marketing.
When using fenced code blocks, the recommendation is to tag the code block with a language so that it can be syntax highlighted. For example:
```
// BAD: Code block with no language tag
```
```javascript
// GOOD: Code block with a language tag
```
Check out the supported languages list for the syntax highlighter we use if you want to double check the language name.
It is also worth noting specifically that if you are using a code block that is an example of a terminal command, the correct language tag is shell-session
. For example:
๐ซBAD: Using shell
, sh
, bash
, or plaintext
to represent a terminal command
```shell
$ terraform apply
```
โ
GOOD: Using shell-session
to represent a terminal command
```shell-session
$ terraform apply
```
The structure of the sidebars are controlled by files in the /data
directory. For example, 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. 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:
.
โโโ docs
โย ย โโโ directory
โย ย โโโ index.mdx
โย ย โโโ file.mdx
โย ย โโโ another-file.mdx
โย ย โโโ nested-directory
โย ย โโโ index.mdx
โย ย โโโ 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-nav-data.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"
}
]
}
]
}
]
A couple more important notes:
- 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
andanother-file
in any order in the sidebar, or even leave one or both of them out, you could not decide to un-nest thenested-directory
object without also un-nesting it in the filesystem. - The
title
property on each node in thenav-data
tree is the human-readable name in the navigation. - The
path
property on each leaf node in thenav-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 thandirectory/index
. A common convention is to set thetitle
of an "index" node to be"Overview"
.
Below we will discuss a couple of more unusual but still helpful patterns.
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:
.
โโโ docs
โย ย โโโ indexless-category
โย ย โโโ file.mdx
// website/data/docs-nav-data.json
[
{
"title": "Indexless Category",
"routes": [
{
"title": "File",
"path": "indexless-category/file"
}
]
}
]
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:
[
{
"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.
Image files should be placed in the website/img
directory.
In markdown, images should be referenced by their absolute path, starting with /img
. This will look like:
![Alt text goes here](/img/docs/my-image.png)
Note: Images aren't expected to work GitHub markdown in previews, but they will work during local preview and Vercel deploy previews
You must add a redirect when you move, rename, or delete documentation pages. Refer to https://github.com/hashicorp/terraform-website#redirects for details.