willtaivvi / substrate-docs

Substrate Developer Hub. Substrate is powered by best in class cryptographic research and comes with peer to peer networking, consensus mechanisms, and much more.

Substrate Developer Hub

https://docs.substrate.io/

This repository serves as the developer hub for the Substrate blockchain framework. The docs are written in MDX format an extension of markdown, processed by Gatsby, and published to https://docs.substrate.io/ .

Contributing

Thank you for your interest in contributing to documentation for the Substrate development framework. As a member of the community, you are invited and encouraged to contribute by submitting issues, offering suggestions for improvements to existing content, adding review comments to existing pull requests, proposing new content, or creating new pull requests to fix issues or provide new content. Please review our contributor guidelines prior to any contribution. If you have any further questions, please do not hesitate to reach out on our Substrate technical community channel! We would love to get to know you and your work!

Directory structure

The content of this website is versioned in separate directories, where v<VERSION> is the convention used. The devhub is then hierarchically separated into the three main types of content: docs, how-to-guides, and tutorials.

Sub folders in these are of the form:

- v<VERSION>
  - <content type>
    - <XX-section>
      - <Y-page>
        - `index.mdx`

By convention we use XX numbering starting at 00 for sections, and Y lettering starting at a for pages.

File directory example: /v3/docs/00-style-and-contributor-guidelines/a-contributor-guidelines/index.mdx

Each index.mdx page has the content to be rendered to this page, and all pages include a header section with a slug item that is used for navigation on the generated site,

URL example: https://docs.substrate.io/v3/contribute/style-guide/

Configuration and styling files for gatsby live primarily in the src folder.

Builder notes

There are some unique requirements to be aware if you are contributing content in this repository to make your life, and the life of the maintainers much easier! Please review the Builder notes in the contributor guidelines if making any non-trivial PRs here.

Production deployment

• main branch is available at: https://docs.substrate.io/

🚀 Quick start

1. Clone the repo

   # create a new folder to get going
   git clone https://github.com/substrate-developer-hub/substrate-docs.git

2. Get setup

   Navigate into your new site’s directory and install all dependencies.

   cd substrate-docs/
   nvm install
   yarn # alias for `yarn install`

3. Configure environment variables

   Copy example.env.development and rename to .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
   GATSBY_MARKETPLACE_URL=http://localhost:8300
   GATSBY_CAREERS_URL=https://careers.substrate.io

4. Fire the engine

   Navigate into your new site’s directory and use the following command to start the development server locally.

   yarn develop

5. Open the code and start customizing!

   Your site is now running at http://localhost:8200/ and your GraphQL data layer is running at http://localhost:8200__graphql.

   Edit to see your site update in real-time on save.

6. Learn more about GatbsyJS

   • Documentation

   • Tutorials

   • Guides

   • API Reference

   • Plugin Library

   • Cheat Sheet

Running link-checking locally

There are more than 10,000 links in this doc repo. So we have a link checker to go through most of them, both internal and external links, to make sure they are valid. We have settings to exclude some external links by default (more on this later).

We use blc (broken-link-checker) for links checking, which is a javascript project. It will be installed when you run yarn install in this package as it is depended on as a development package.

To run link checker, first in one terminal, build the gatsby site with clean cache:

yarn serve:fresh

This command takes a minute or two for the above command to complete, have the site built, and finally serving it at https://localhost:9000.

In another terminal, run:

yarn checklinks-local

You can further configure it in package.json file. Currently it has a list of paths being excluded. These paths are not regex-supported and just doing a plain string matching. They are excluded because for:

• /rustdocs: all paths to /rustdocs/<splat> are going to be redirected to https://paritytech.github.io/substrate/. The redirection is handled by netlify redirect feature. Gatsby server will just rendered them as 404 pages.

• /crates.io, /fonts.gstatic.com, /github.com, /wwww.nuget.org: they either have rate-limiting check or doesn't welcome web crawlers to fetch them and just return a 404 page.

Link checking as part of Github workflow

We configured a Github workflow to build the Gatsby site in production as a docker image and push it to Docker hub at jimmychu0807/substrate-docs. The image is then launched as a service in the next CI/CD job. checklinks is run against the running gatsby site in the docker container to check all links.

Security

Please report security bugs as stated in the static/security.txt file in this repository.

License

TBD