Setup Markdown
Prepare the repo
Requirements
- Node.js version 18.0 or above
- Yarn 1.22.x
- The minimum required version is TypeScript 5.1
- IntelliJ IDEA with markdown plugins
- Markdown editors (Optional)
Cloning Github ctm-docs repo
$ git clone https://github.com/comparethemarketau/ctm-docs.git
# OR
$ git clone git@github.com:comparethemarketau/ctm-docs.git
It consists of Docusaurus engine and our documents. You can download dependencies.
# install dependencies
$ yarn
Writing in your local
When you create or modify your document, running it on your local is useful before deploying it.
First, check out the develop branch or your feature branch. All your new changes should be in the develop branch. Then, you can merge it after finishing the document. Just open PR, review, and merge it. The build pipeline will publish it after merging into the main branch.
NOTE
If you want to fix typo or change very little, you can modify a file in the main branch directly. Mostly, you may use develop branch. But there are no limitation.
package Installation
$ git checkout develop
Local Development
$ yarn start
This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server. You can write and monitor a document at the same time.
Then, you may use IDE like IntelliJ IDEA or Markdown editors.
Build and Deployment
Build
$ yarn build
Before committing your new changes, this command generates static content into the build directory, which can be checked using any static content hosting service.
Deployment
After finishing the document, you can open a PR to review it on the develop branch. Once the develop merges into the main branch, the github pipeline will push to the gh-pages to show the static site automatically. If you get a build error, check your document structure. You can see more detail.
You can see the Github Actions tab how they deploy to the page. We don't have a specific domain yet. We can access the url which is generated by Github page.
Use docs; a set of documents (Optional)
Docs Template
I've created an initial structure of docs directories each projects.
docs-template
Most projects are already created in the repo. However, if you want a new project, You can copy this directory to a new docs directory with a name. For example, I recommended that the directory structure be consistent, like the one below.
docs-template/
├── 10-intro.md # First, the entry document for a project
├── 20-prerequisites # Essential information
│ ├── 01-permissions.md # How to access
│ ├── 02-dev-setup.md # How to setup
│ ├── 03-dev-environments.md # Development Environments (dev/uat/prod)
│ ├── 04-branch-strategy.md # How to checkout, open PR, merge
│ └── 05-naming-conventions.md # nameing conventions
├── 30-architecture-overview # In order to understand
│ ├── 10-frontend # Understand the Frontend
│ └── 20-backend # Understand the Backend
├── 40-library-dependencies # Major library usages
├── 50-ui-ux-design # UI/UX desgin guideline and components
├── 60-implementation # Show implement methods
├── 70-tests # How to test
└── 80-deployments # How to deploy
Most of time, you will create a .md file using any markdown editors. Open the directory, and create it!
Document directories prefer to have dash(-) separated name and the directory has pre-defined name markdown file.
intro.md: The directory main index file to explain the directory._category_.json: This file explains a directory with title and description. it is hidden from publishing. (underscore started file will be ignored)assets: This is a directory contains images like.png, or fixed resources like.doc,.zipfor documents.01-xxx.md: If a document has number prefix, it will be ordered by the number. You can also usesidebar_position: 1in the frontmatter value on top of the document.
You can use your favorite editor like VSCode or IntelliJIdea. Also, you can use specific markdown editors. See more detail.
- MarkText : Free, but limited features.
- Typora : One-time paid, real time editing, easy to use (recommended)
- Obsidian : Community/Offline is free to use. (Cloud should be paid)
Create docs (Optional)
If you want to have a menu on the top navigation for a set of documents, you should define a directory for it by copying the template. You can skip this section mostly because I have already created the structures.
Preparation
Use markdown .md syntax, or you can use React syntax in your document.
First, you should clone the ctm-docs repository in your local. And then, you can write a document on one of the document directories stating with docs-. For example,
docs-generaldocs-simples-app
If you want to create a separate menu section, create a directory with the prefix.
docs-[your-doc-name]
Then, add one more plugin-content-docs in the plugins section.
plugins: [
"@orama/plugin-docusaurus-v3",
[
'@docusaurus/plugin-content-docs',
{
id: 'docs-simples-app',
path: 'docs-simples-app',
routeBasePath: 'docs-simples-app',
sidebarPath: './sidebarsKotlin.ts',
showLastUpdateAuthor: true,
showLastUpdateTime: true,
editUrl: 'https://github.com/comparethemarketau/ctm-docs/edit/develop',
},
],
[
'@docusaurus/plugin-content-docs',
{
id: 'docs-2',
// other options
},
],
]
...
A document (or page) structure
Front matter (optional)
The front matter is used to provide additional metadata for your doc page. Front matter is optional. Docusaurus will be able to infer all necessary metadata without the front matter. For example,
---
id: doc-with-tags
title: A doc with tags
sidebar_position: 2
tags:
- Demo
- Getting started
---
your markdown contents here
id is unique key for a document routing, it is usually generated by the engine automatically.
title will be override first level of markdown heading. If you don't have title and 1 level heading, file name will be the title.
tags is very useful for categorising documents. All front matter are optional.
Here is much complex front matter. Example,
---
id: doc-markdown
title: Docs Markdown Features
hide_title: false
hide_table_of_contents: false
sidebar_label: Markdown
sidebar_position: 3
pagination_label: Markdown features
custom_edit_url: https://github.com/facebook/docusaurus/edit/main/docs/api-doc-markdown.md
description: How do I find you when I cannot solve this problem
keywords:
- docs
- docusaurus
image: https://i.imgur.com/mErPwqL.png
slug: /myDoc
last_update:
date: 1/1/2000
author: custom author name
---
# Markdown Features
My Document Markdown content
Blog Structure
Blog is more like logging articles for your finding or interesting. To publish in the blog, create a Markdown file within the blog directory.
blog/
├── 2019-05-28-first-blog-post.md
├── 2019-05-29-long-blog-post.md
├── 2021-08-01-mdx-blog-post.mdx
├── 2021-08-26-welcome
│ ├── docusaurus-plushie-banner.jpeg
│ └── index.md
└── authors.yml
Here is the example,
---
title: Welcome Docusaurus
description: This is my first post on Docusaurus.
slug: welcome-docusaurus-v2
authors:
- name: Joel Marcey
title: Co-creator of Docusaurus 1
url: https://github.com/JoelMarcey
image_url: https://github.com/JoelMarcey.png
- name: Sébastien Lorber
title: Docusaurus maintainer
url: https://sebastienlorber.com
image_url: https://github.com/slorber.png
tags: [hello, docusaurus-v2]
image: https://i.imgur.com/mErPwqL.png
hide_table_of_contents: false
---
Welcome to this blog.
<!-- truncate -->
This is my first post on Docusaurus 2.
A whole bunch of exploration to follow.
Use the <!--truncate--> marker in your blog post to represent what will be shown as the summary when viewing all published blog posts. Anything above <!--truncate--> will be part of the summary. Note that the portion above the truncate marker must be standalone renderable Markdown.
Docusaurus will extract a YYYY-MM-DD date from many patterns such as YYYY-MM-DD-my-blog-post-title.md or YYYY/MM/DD/my-blog-post-title.md. This enables you to easily group blog posts by year, by month, or to use a flat structure.