Arundo Docs Contributors Guide¶
These docs explain how to create, build, and update our online docs. All of our docs are written in GitHub Flavored Markdown (GFM) and built with the MkDocs static site generator.
Here are some important things to know before you get started.
Markdown¶
You must write the docs in GitHub Flavored Markdown (GFM). However, the theme for the docs features a number of extensions that give you the ability to add elements using custom markdown syntax.
Check out these resources to learn more:
| Resource | Description |
|---|---|
| Markdown Cheatsheet | Learn the basics about writing in markdown. |
| MkDocs User Guide | Learn how to write and layout markdown files. |
| Extensions | Learn the special markdown syntax you can use to add callouts and code blocks. |
MkDocs¶
The docs are built using the MkDocs static site generator. MkDocs is a fast and lightweight static site generator that builds HTML sites we can host internally or externally.
MkDocs operates from the command-line. Here is a list of commands you can use.
| Command | Usage |
|---|---|
mkdocs serve |
Runs a development server for the docs at http://localhost:3000. As you make updates locally, the docs reload automatically to give you a live preview of your changes in the browser. |
mkdocs build |
Creates a production build of the docs in the site folder. You must build the docs right before you push local changes to GitHub and submit a pull request. |
mkdocs --version |
Displays the version of MkDocs you currently have installed. |
Theme¶
The arundo-docs-theme we use for the docs is a custom version of the Material Design theme.
Hosting¶
We host doc sites from the arundo-docs-prod-global resource group in Azure.
Security¶
Doc sites can be made accessible to anyone or restricted to a specific group of users. There are multiple options for securing docs with depending on the intended audience for the docs.