Helium Documentation
Documentation for the Helium network.
Requirements
Installation
$ yarn
Local Development
$ yarn start
This command starts a local development server and open up a browser window. Most changes are reflected live without having to restart the server.
Contributing
Documentation is managed by Helium, but supported by the community.
Please see CONTRIBUTING.md for more instructions.
Creating a New Doc
When authoring a new doc, be sure to apply prettier to it during review. For
example: npx prettier --write --prose-wrap always docs/blockchain/new_doc.mdx
It will apply appropriate line wraps and other formatting niceties.
Editing an Existing Doc
When editing an existing doc, line wrap should not be applied (don't run
prettier), and lines that run wider than 80 chars in width are okay. Applying
prettier would cause many unimportant line changes and make review more
difficult.
Instead, from time to time, prettier will be run against the documents and
those unimportant commits will be added to .git-blame-ignore-revs
Use the style guide found here to learn what markdown syntax is available.
For more advanced content consider using JSX.
Linking to Other Docs
When linking to other docs always use full path links or abbreviated links to full path links at the bottom of the doc. Abbreviated links help improve readability of the raw markdown and makes common links reusable in the same doc.
Abbreviated Links Example:
If you would like to link to the development devices introduction page found at
/use-the-network/devices/development, use
[development devices][devices.development] inline with your text content.
Next, create the link to the full path at the very bottom of the doc markdown
like this [devices.development]: /use-the-network/devices/development.
Adding Images
When adding images, use the method shown below.
---
id: my-doc
title: My Doc
---
// Add to the top of the file below the front matter.
import useBaseUrl from '@docusaurus/useBaseUrl';
...
<img alt="Image Description" src={useBaseUrl('img/image.svg')} />
Image Naming
When naming images with multiple words, use - to separate the words only.
Adding a New Doc
Create a new *.mdx extension file following the existing naming conventions.
Doc Front Matter
When creating a new doc, use the following front matter at the very top of the doc with the following fields:
id: This should match the filename without the extension.
hide_title: Always set this true.
sidebar_label: This should match id name but with spaces and capitalized
first letters.
---
id: devices
hide_title: true
sidebar_label: Devices
---
slug: If the doc id path has repeated sections like the following doc path
use-the-network/devices/devices, define a slug: field in the front matter to
make it pretty as shown below. This way when this doc is navigated to, the URL
shown will not have repeating sections names in it.
slug: use-the-network/devices
Check for dead links
yarn build does a good job of checking for dead links.
TODO: add to CI
Sidebar Links
Learn how to create sidebar links here.
Category Type
When adding items use the raw id path, slug paths will not work.
Attribution
This website is built using Docusaurus 2, a modern static website generator.