Open-source template of Setu Docs
- Set up Guide
- Content editing guide
- Contribution guide
- Adding a new product category and a new product
- Using React components in MDX files
- Folder Structure
- VS Code
- Git
- node v14 or above
If you know these, you can go ahead and set up. Otherwise, ask someone from Developer relations or the Design team for help.
Open your terminal and navigate to a folder where you want to clone this repository, such as Documents. Run this command.
git clone https://github.com/SetuHQ/docter.git
Recommend using yarn over npm
- Install dependencies with
yarn install - Run the app with
yarn dev
You should be able to see docs local version at http://localhost:3000
For easy syntax higlighting, install this VS Code extension https://marketplace.visualstudio.com/items?itemName=silvenon.mdx
All the files to edit content are inside
contentfolder. You are not required to touch any other folder.
---
sidebar_title: Sample Page
page_title: Sample page — Setu Docs
order: 0
visible_in_sidebar: true
---
## This is heading 2
And this is a paragraph text
- And a bullet point, **in bold**
As seen above, every MDX file has two main sections — frontmatter and the actual content
Frontmatter is information about the page, helping the CMS to know what to do with page.
---
sidebar_title: Overview
page_title: Test product 1 Overview
order: 0
visible_in_sidebar: true
---
sidebar_title describes the name to be displayed in the sidebar
page_title describes the title of the page
order describes order in which this MDX file should be displayed
visible_in_sidebar describes whether this item should be displayed in the sidebar or not
Please note, all the above paramaters are required in front-matter
Only for API reference pages—
- If the API reference is in JSON format, we need to add a new field inside the frontmatter
---
sidebar_title: Overview
page_title: Test product 1 overview
order: 0
visible_in_sidebar: true
api_reference : "<API reference in JSON format>"
---
Please note,
api_referenceis an optional field and can be used only to display API references. We use Redoc component to render the API specifications
- If the API reference is via Postman collection, you can add an entry in
redirects.jsonto redirect to the Postman collection URL
This is the content that is actually shown on the page when processed by the CMS. For help on Markdown syntax, refer this Markdown cheatsheet.
## This is heading 2
And this is a paragraph text
- And a bullet point, **in bold**
Let's start with an example. We will—
- Create a single page with name
Introductionand pathintroduction - Create a category with name
Test categoryand pathtest-category - Create two products
- Name
Test product 1, pathtest-product-1 - Name
Test product 2, pathtest-product-2
- Name
- Create an Overview page for each product with some content in it
Create a MDX file with name, 'introduction.mdx' in content folder.
Add frontmatter and content into the Introduction page
Create a new folder with name, 'test-category' in content folder.
Create an index.mdx file inside test-category with details of the category in front-matter.
Very Important
You should always have an
index.mdxfile inside all the folders that you create incontent
Create two new folders with names test-product-1 and test-prodcut-2 inside test-category folder.
Create an index.mdx file inside test-product-1 with details of the product in front-matter.
Create a file overview.mdx inside test-product-1 and add some sample content like this—
---
sidebar_title: Sample Page
page_title: Sample page
order: 0
visible_in_sidebar: true
---
## This is heading 2
And this is a paragraph text
- And a bullet point, **in bold**
Create similar mdx files inside test-product-2 and we are done!
You can find the exact content in the repo described in the example.
List of all components and their usage can be found by visiting http://localhost:3000/docs-components
MIT license.