To run Docs v2 for the first time you'll:
- Clone the
monorepo
- Navigate to
docs-v2
- Use
just install
to install all packages and dependencies - Run
just build
Now you're ready to work! You can now run pnpm dev
in your command line.
The docs will now be accessible in your browser.
Terminal will watch for changes, and recompile when they're detected.
You'll need to refresh your browser to view changes.
Check your Node version
You can check your Node version by running node -v
in your command line.
Docs v2 is running on Node
18.11.0
Check your NPM version
You can check your Node version by running npm -v
in your command line.
Clear the server cache
Run just clear_cache
to reset Next.js
Each Doc is it's own individual Markdown file in /content/pages
.
The pages are organized in navigation.json
There are 4 steps to add a new page to the docs:
1. Create the page
First you'll create a new .mdoc
file in /content/pages
. The file name will be the url slug.
example-page.mdoc
2. Add a page title
You'll add the page title, by adding the following Markdown at the top of your file
---
title: Example Page Title
---
3. Add the page to the navigation
The sidebar navigation lives in navigation.json
. Open this file, and you'll see an outline of all the pages in Docs.
This data is structured like so:
- There are three top level nav items: Guides, Reference, API
- Within each of those 3 is an array of subtopics (e.g. Getting Started, Collecting Subscribers)
- Each subtopic has it's own array of articles (
page
)
In addition to page
s and item might also be a divider
. This can be used to break up the content, for example separating FAQs.
Add the new page in the correct section, you'll find the correct Subtopic, and create a new object.
Be sure to use the file name without the
.mdoc
file extension
For example:
"top-level-nav": [
{
"name": "Sub Topic title here",
"items": [
{
"discriminant": "page",
"value": "page-1"
},
{
"discriminant": "page",
"value": "page-2"
},
{
"discriminant": "divider",
"value": "FAQ"
},
{
"discriminant": "page",
"value": "faq-1"
},
{
"discriminant": "page",
"value": "faq-1"
}
]
}
]
4. Updating search index
After you add a new page, you'll need to update the search index for tests to pass. This has been added to the build command:
just build
Due to a Markdoc limitation, multiline code blocks require an additional flag to render correctly. If you don't have this tag, all content below the code sample gets "eaten" (for lack of a better term)
To resolve this, you can append {% process=false %}
after the three opening tick marks
{% if syntax= "looks like handlebars or django" %}
make sure you have the process false added
{% endif %}
These code samples won't work with a snippet like the Renderable/Preview, etc. It throws a syntax error because the sample is using the same code syntax as the snippet itself.
Instead these will need to be wrapped in the regular Markdown code block syntax
{% if syntax= "looks like handlebars or django" %}
just make it a regular markdown code block
{% endif %}
Here's more info on this:
This snippet requires that all language flags are present, even if there isn't a code sample in that particular language.
It'll look something like this:
{% multilanguageSnippets
python="sample.py"
ruby=""
curl="sample.sh"
javascript="" /%}
The core tsconfig.json file contains an incremental: true
flag which does not work in the context of tests or stand-alone files.