https://github.com/gruntwork-io/docs
Gruntwork docs files plus a set of tools to auto-generate a docs website from package markdown files.
https://github.com/gruntwork-io/docs
Last synced: 2 days ago
JSON representation
Gruntwork docs files plus a set of tools to auto-generate a docs website from package markdown files.
- Host: GitHub
- URL: https://github.com/gruntwork-io/docs
- Owner: gruntwork-io
- License: other
- Created: 2016-10-20T22:51:10.000Z (over 8 years ago)
- Default Branch: main
- Last Pushed: 2025-06-05T05:40:00.000Z (7 days ago)
- Last Synced: 2025-06-05T07:11:34.232Z (7 days ago)
- Language: JavaScript
- Homepage: https://docs.gruntwork.io
- Size: 84.9 MB
- Stars: 28
- Watchers: 16
- Forks: 42
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
- Codeowners: CODEOWNERS
- Support: docs/support.mdx
Awesome Lists containing this project
- jimsghstars - gruntwork-io/docs - Gruntwork docs files plus a set of tools to auto-generate a docs website from package markdown files. (JavaScript)
README
# Docs Site
This website is built using [Docusaurus 3](https://docusaurus.io/), a modern
static website generator.
## Overview
### Docs Sourcer
The vast majority of content in the `docs` folder is maintained by developers and not automation.
There are, however, some types of docs that are maintained by a tool called `docs-sourcer`. You can
identify those files by the `##DOCS-SOURCER-START` tag at the end of the file. In general
this is content that is pulled from external sources, such as change logs, release notes and
GitHub discussions.
Docs Sourcer is generally run in CI or via webhooks and doesn't have to be run locally. If, however, you do need
to run it locally you will need access to various secrets. These secrets live in 1password under a secure note called
"docs sourcer .env file".
## Installing dependencies
```sh
yarn
```
## Local development
```sh
yarn start
```
This command starts a local development server and opens up a browser window.
Most changes are reflected live without having to restart the server.
### Running a production build locally
```sh
yarn build && yarn serve
```
This will create and serve a production build. This can be used to verify the
expected behaviors in a production environment and view the Google analytics.
# Linking to other pages
We only allow absolute links to other internal docs pages, e.g. `(modules)[/2.0/docs/library/concepts/modules]`. This is to ensure that links work when the site is deployed to s3 which always appends a trailing slash.
# Customizable Values
It's often useful to present the user with the ability to edit a variable inline to documentation. For example, you're about to present a block of code that references an S3 bucket name. Rather than put in a fixed placeholder like which the user has to manually edit, you can use our CustomizableValue component. This component will render as a clickable text field which, when clicked, switches to an input. Any inputted characters will be auto-propegated to all other instances of the component that share the same ID. You can use this component both as a React component and inline to MDX code blocks. We have swizzled the CodeBlock components to make this possible.
Example usage:
As a component:
```js
```
Using the \$\$ID\$\$ syntax inside a code block
```md
This is inside a code block, $$BUCKET_NAME$$
```
# Spell Check
The codebase (in `docs/2.0/`) is spell checked via CI using `cspell`. We have a custom dictionary in `./custom-dictionary.txt`. You can test spelling locally with `yarn spellcheck` (your IDE likely also automatically does this). Feel free to add new terms to the dictionary that are bespoke to Gruntwork. You can [disable spell check](https://cspell.org/configuration/document-settings/) for a block using the following pattern:
```
MY POURLEY SPELLED WURDS
Content that is once again spell checked.
```
# Automated Pull Request Flows
There are two main categories of the Automated PRs that get opened in the Docs repostory:
* PRs for Pull requests in module repositories - have "Automated Preview" title
* PRs for Releases in module repositories - have "Automated Update" title
## Automated Preview PRs
The "Automated Preview" PRs are meant for the developers of different modules to be responsible for their docs while developing so they can ensure correctness. However, they are not intended to be merged since Docs are tied to versions of the modules
When the Pull request in a module repository is closed or merged, the associated "Automated Preview" docs PR is automatically closed.
## Automated Updated PRs
When a module repository gets a new release, the "Automated Update" pull request is opened on the docs site and that is what is intended to be merged and eventually released to the Docs site.
## Automation Setup
The automation of the PRs is accomplished via docs-sourcer ([docs](https://github.com/gruntwork-io-team/dogfood-infrastructure-live/blob/main/OPERATOR.md#docs-sourcer) - [repo](https://github.com/gruntwork-io/docs-sourcer)), ultimately its a lambda function receiving GitHub webhooks.