Documentation
The source code for this site can be found at the Docs and Developer Site repository.
Get started in 5 minutes
- Make sure all the dependencies for the website are installed. In
website/
:
# Install dependencies
$ cd website
$ yarn
- Run your dev server:
# Start the site
$ yarn start
Documentation is the single source of truth (SSOT)
The docs are the SSOT for information about how to configure, use, and troubleshoot Minds products and features.
Docs-first methodology
If the answer to a question exists in documentation, share the link to the docs instead of rephrasing the information.
When you encounter new information not available in Minds’s documentation (for example, when working on a support case or testing a feature), your first step should be to create a merge request to add this information to the docs. You can then share or screenshot the MR in order to communicate this information.
Link instead of summarize
There is a temptation to summarize the information on another page. This will cause the information to live in two places. Instead, link to the SSOT and explain why it is important to consume the information.
Formatting
Headers
The largest tier of headers should have two hashes, e.g. ## My h1 primary header
. If you use one hash, it won't work with the navigation sidebar.
Only capitalize the first letter of your header, unless it includes a proper noun:
### My cool subheader with many words
### My cool Minds subheader that contains a proper noun
Editing an existing docs page
Edit by clicking the "edit" button at the top of the docs site page, or by navigating to docs/
(or website/blog
, if it's a blog) and editing the corresponding document:
docs/doc-to-be-edited.md
---
id: page-needs-edit
title: This Doc Needs To Be Edited
---
Edit me...
Click here for more info on docs, or here for blogs.
Adding Content
Adding a new docs page to an existing sidebar
- Create the doc as a new markdown file in
/docs
, exampledocs/newly-created-doc.md
:
---
id: newly-created-doc
title: This Doc Needs To Be Edited
---
My new content here..
- Refer to that doc's ID in an existing sidebar in
website/sidebars.json
:
// Add newly-created-doc to the Getting Started category of docs
{
"docs": {
"Getting started": [
"quick-start",
"newly-created-doc" // new doc here
],
...
},
...
}
Re-run yarn start
to see the changes in the sidebar.
For more information about adding new docs, click here.
Adding a new blog post
- Make sure there is a header link to your blog in
website/siteConfig.js
:
website/siteConfig.js
headerLinks: [
...
{ blog: true, label: 'Blog' },
...
]
- Create the blog post with the format
YYYY-MM-DD-My-Blog-Post-Title.md
inwebsite/blog
:
website/blog/2018-05-21-New-Blog-Post.md
---
author: Frank Li
authorURL: https://twitter.com/foobarbaz
authorFBID: 503283835
title: New Blog Post
---
Lorem Ipsum...
For more information about blog posts, click here
Adding items to the top navigation bar
- Add links to docs, custom pages or external links by editing the headerLinks field of
website/siteConfig.js
:
website/siteConfig.js
{
headerLinks: [
...
/* you can add docs */
{ doc: 'my-examples', label: 'Examples' },
/* you can add custom pages */
{ page: 'help', label: 'Help' },
/* you can add external links */
{ href: 'https://gitlab.com/minds', label: 'GitLab' },
...
],
...
}
For more information about the navigation bar, click here.
Adding custom pages
- Docusaurus uses React components to build pages. The components are saved as .js files in
website/pages/en
- If you want your page to show up in your navigation header, you will need to update
website/siteConfig.js
to add to theheaderLinks
element:
website/siteConfig.js
{
headerLinks: [
...
{ page: 'my-new-custom-page', label: 'My New Custom Page' },
...
],
...
}
For more information about custom pages, click here.
Adding an image to a docs page
- Add the image file to
docs/assets/
- Add a "Click to enlarge" link below images that depict small details/text
![My cool diagram](assets/my-cool-diagram.png "My cool diagram's alt text")
[Click to enlarge](assets/my-cool-diagram.png)
Resources and credits
Full documentation can be found on the docusaurus website.
A portion of this guide's content is taken from GitLab's excellent documentation styleguide.