Thank you for your interest in contributing to documentation for Substrate! As a member of the community, you are invited and encouraged to contribute by submitting issues, offering suggestions for improvements to existing content in the form of a pull request, adding review comments to existing pull requests and issues, proposing new content, or creating new pull requests to fix issues or provide new content.
All .md
files added to ./content/md/en/docs/
folder will output an URL path without the /docs
prefix, eg.:
index.md
for a category page :./content/md/en/docs/reference/index.md
→/reference/
<article-name>.md
for an article in its parent category./content/md/en/docs/reference/glossary.md
→/reference/glossary/
You can use any structure nesting needed, there is no limit of depth.
- use
./content/media/images/docs/
folder for images to be included in/docs/*/*.md
files - source images in
.md
:/media/images/docs/path/to/your/image/<image>.ext
- update
./content/config/nav.yaml
to add or amend items and linking to your content- an exception being
./content/md/en/docs/reference/how-to-guides/...
files that should only be listed on the main how-to guide page in the index page for these pages:./content/md/en/docs/reference/how-to-guides/index.md
, not to be included in the sidebar.
- an exception being
This config file is used to generate sidebar menu where:
- menu is populated from the
menu
sequence (respecting order) - menu supports three level hierarchy
- menu accepts external links, eg.:
https://substrate.io
Navigate into your cloned local repo directory and install all dependencies.
# https://github.com/nvm-sh/nvm is suggested, so that you
# switch to the correct version of node set in the .nvmrc file
nvm i
# Install dependencies
yarn
gatsby-plugin-substrate submodule
This website uses a submodule for shared components. To set it up please refer to the gatsby-plugin-substrate repository.
git submodule update --init --recursive
To update the submodule to the latest main branch, run:
git submodule update --remote
Configure environment variables
Copy example.env.development
into a new .env.development
file.
cp example.env.development .env.development
Config URL variables based on your preferable local setup. URL will be used for links generation between Substrate websites.
Default localhost port configuration:
GATSBY_WEBSITE_URL=http://localhost:8100
GATSBY_DOCS_URL=http://localhost:8200
Start development server
Navigate into your new site’s directory and use the following command to start the development server locally.
yarn develop
Troubleshooting
It is sometimes the case that gastby's cache gets corrupted when making changes. If you run into issues in local development, try to clean this and restart:
yarn clean
yarn develop
Please report security bugs as stated in the static/security.txt
file in
this repository.
TBD, please open an issue to request any use outside of the official host https://docs.substrate.io/ at this time.