All documentation in web-unified-docs is written in Markdown, using .mdx files that support extended MDX syntax and custom components.
Every .mdx file must begin with YAML frontmatter that provides at minimum a title and description. Some frontmatter fields (created_at, last_modified) are autogenerated and must not be manually edited.
---
title: 'My Title'
description: "A thorough, yet succinct description of the page's contents"
---
content/docs/hello.mdx is served from /docs/hello.
Files and directories only render and publish to the website if they are included in the navigation sidebar data. Any file not included in sidebar data will not be rendered or published.
Standard Markdown
The following standard Markdown elements are supported across all pages.
Headings
Use ATX-style headings. The page’s H1 is typically set to match the title frontmatter field.
# H1 — Page title
## H2 — Major section
### H3 — Subsection
#### H4 — Minor subsection
Lists
- Unordered item
- Another item
- Nested item
1. Ordered step
1. Next step
1. Nested step
Code blocks
Always include a language tag on fenced code blocks:
```shell-session
$ vault status
```
```json
{ "key": "value" }
```
```hcl
resource "aws_instance" "example" {
ami = "abc-123"
instance_type = "t2.micro"
}
```
Inline code
Use backticks for inline code, file paths, CLI flags, and configuration keys:
Run `vault status` to check the server state.
Edit the `config.hcl` file and set `ui = true`.
Links
[Link text](https://developer.hashicorp.com)
[Relative page link](../other-page)
Tables
| Column 1 | Column 2 | Column 3 |
| :------- | :------: | -------: |
| Left | Center | Right |
MDX enhancements
HashiCorp documentation supports custom Markdown enhancements to produce pages with tabs, named code blocks, badges, and alert boxes.
Callout boxes
Use callouts to draw attention to important information. Choose the type that matches the severity and nature of the message.
<Note>
Supplementary information the reader can safely skip.
</Note>
<Tip>
A recommendation or best practice that improves the outcome.
</Tip>
<Warning>
A potentially destructive action or important caveat the reader must not overlook.
</Warning>
<Info>
Helpful context such as permissions, prerequisites, or background.
</Info>
Tabs
Use tabs to show parallel content for different environments, operating systems, or approaches without duplicating the surrounding prose.
<Tabs>
<Tab title="Linux">
```shell-session
$ sudo apt-get install vault
```
</Tab>
<Tab title="macOS">
```shell-session
$ brew install vault
```
</Tab>
<Tab title="Windows">
Download the binary from the releases page and add it to your PATH.
</Tab>
</Tabs>
Code groups
Use code groups to display multiple related code files or examples with labeled tabs.
<CodeGroup>
```hcl main.tf
resource "aws_instance" "web" {
ami = var.ami_id
instance_type = "t3.micro"
}
```
```hcl variables.tf
variable "ami_id" {
type = string
description = "The AMI ID to use for the instance."
}
```
</CodeGroup>
img or public/img directory. Reference images using a root-relative path and always include descriptive alt text:
- A sentence before the image that introduces it.
- A sentence after the image that explains or provides additional context.
For diagrams that explain complex workflows, prefer PNG or SVG formats. Avoid large images that slow page load times.
Previewing your changes
To preview content locally, run make from the web-unified-docs directory. This uses Docker to build the documentation website locally.
Wait for both the unified-devdot-api and dev-portal containers to finish starting before testing. Once ready, access the preview at http://localhost:3000.
To stop the preview environment:
To stop and remove local Docker images:
$ make clean CLEAN_OPTION=full