Skip to main content

Markdown Style Guide

This guide establishes consistent markdown formatting standards for all documentation in this project and can be applied across different documentation platforms.

📁 File Organization​

File Naming​

Standards:

  • Use kebab-case for file names: react-router-configuration.md
  • Be descriptive but concise: git-commits.md not git.md
  • Use meaningful prefixes for related content: nodejs-setup.md, nodejs-database.md

Examples:

✅ Good
git-commits.md
pull-requests-and-releases.md
styled-components.md

❌ Avoid
Git_Commits.md
PR and releases.md
styledcomponents.md

Folder Structure​

Standards:

  • Use kebab-case for folder names
  • Group related content in logical folders
  • Include _category_.json for each subfolder to control Docusaurus navigation

Folder Structure Pattern:

docs/
├── topic-name/
│   ├── _category_.json
│   ├── overview.md
│   ├── subtopic-1/
│   │   ├── _category_.json
│   │   ├── concept-a.md
│   │   └── concept-b.md
│   └── img/
│       └── diagram.png

📄 Front Matter Standards​

Required Front Matter​

All .md files must include front matter with these fields:

---
sidebar_position: 1
title: Page Title
description: Brief description for SEO and navigation
---

Optional Front Matter​

---
sidebar_position: 1
title: Page Title  
description: Brief description for SEO and navigation
hide_table_of_contents: false  # Default: false
slug: custom-url-slug          # Only if needed
tags: [react, styling]         # For categorization
---

Front Matter Guidelines​

  • sidebar_position: Use integers (1, 2, 3...) to control order
  • title: Use title case, be specific and descriptive
  • description: Keep under 160 characters, focus on value provided
  • hide_table_of_contents: Only set to true for short pages

📝 Heading Conventions​

Heading Hierarchy​

Standards:

  • Use only one H1 per document (the title after front matter)
  • Follow logical hierarchy: H1 → H2 → H3 → H4
  • Don't skip heading levels
  • Use sentence case for headings

Structure Pattern:

# Document Title (H1 - only one per doc)

## Major Section (H2)

### Subsection (H3)

#### Details (H4)

##### Rarely needed (H5)

###### Avoid using (H6)

Heading Style​

Examples:

✅ Good
# Git commit standards
## Branch naming conventions
### Feature branch format

❌ Avoid  
# GIT COMMIT STANDARDS
## Branch Naming Conventions
### feature_branch_format

💻 Code Block Standards​

Code Fencing​

Always use triple backticks with language specification:

✅ Good
```javascript
const example = "code";
npm install package

❌ Avoid

const example = "code";

indented code blocks


### Language Identifiers

**Common language identifiers:**
- `javascript` or `js`
- `typescript` or `ts`
- `bash` or `shell`
- `json`
- `yaml`
- `markdown`
- `css`
- `html`

### Code Block Guidelines

**Inline Code:**
- Use single backticks for: `function names`, `file names`, `commands`
- Example: Use the `useState` hook in `App.tsx`

**Multi-line Code:**
- Include context and explanations
- Keep examples realistic but concise
- Add comments when helpful

## 🔗 Link Guidelines

### Internal Links

**Link to other documentation pages:**
```markdown
✅ Good
See [Git Commit Standards](./standards/git-commits.md)
Check the [React folder structure](../react/folder-structure/high-level.md)

❌ Avoid
See [here](./standards/git-commits.md) for git standards
Click [this link](../react/folder-structure/high-level.md)

Always use descriptive link text:

✅ Good
Learn more about [conventional commits](https://www.conventionalcommits.org/)
Install from the [official Node.js website](https://nodejs.org/)

❌ Avoid
Learn more [here](https://www.conventionalcommits.org/)
Go to https://nodejs.org/ to install
  • Use descriptive link text that makes sense out of context
  • Test all links during reviews
  • Use relative paths for internal documentation
  • Open external links in the same window (default behavior)

🖼️ Image and Media Standards​

Image Organization​

Structure:

docs/
├── topic/
│   ├── content.md
│   └── img/
│       ├── diagram.png
│       └── screenshot.png

Image References​

Standards:

✅ Good
![Three-tier architecture diagram](./img/three-tier-architecture.png)

<!-- For images in static folder -->
![DECODE Logo](/img/decode-logo-dark.svg)

❌ Avoid
![](./img/diagram.png)
![image](./screenshot.png)

Image Guidelines​

  • Use descriptive alt text for accessibility
  • Optimize images for web (reasonable file sizes)
  • Use consistent naming: kebab-case.extension
  • Place images in img/ folders within relevant sections

📊 Table Formatting​

Table Structure​

Standards:

| Column 1    | Column 2           | Column 3        |
| ----------- | ------------------ | --------------- |
| Row 1 Col 1 | Row 1 Col 2        | Row 1 Col 3     |
| Row 2 Col 1 | Longer content here| Row 2 Col 3     |

Table Guidelines​

  • Use pipes | to separate columns
  • Include header separator row with dashes
  • Align content consistently (left-align is default)
  • Keep table content concise

Alignment options:

| Left        | Center       | Right       |
| :---------- | :----------: | ----------: |
| Default     | Centered     | Right-align |

🎯 Docusaurus-Specific Rules​

Category Configuration​

category.json format:

{
  "label": "Section Name",
  "position": 1,
  "link": {
    "type": "generated-index"
  }
}

Guidelines:

  • Use descriptive labels
  • Set logical position numbers
  • Include generated-index for automatic landing pages

MDX Features​

When using MDX components:

import CustomComponent from '@site/src/components/CustomComponent';

<CustomComponent prop="value" />

Docusaurus Assets​

Static assets:

![Logo](/img/logo.svg)           <!-- From static/img/ -->
![Local](./img/local-image.png)  <!-- From docs/section/img/ -->

✅ Content Best Practices​

Writing Style​

Be clear and actionable:

  • Use active voice: "Run the command" vs "The command should be run"
  • Write for your audience: assume basic technical knowledge
  • Use bullet points and numbered lists for clarity
  • Include examples for complex concepts

Content Organization​

Structure documents logically:

  1. Overview - What this covers and why it matters
  2. When to apply - Specific use cases
  3. Guidelines - The actual standards
  4. Examples - Concrete implementations
  5. Anti-patterns - What to avoid

Consistency Standards​

  • Use bold for emphasis and important terms
  • Use italic sparingly for subtle emphasis
  • Use inline code for technical terms, file names, commands
  • Be consistent with terminology throughout

🚫 Anti-patterns to Avoid​

Common Mistakes​

Headings:

❌ Avoid
# SHOUTING HEADINGS
### Skipping H2 and going to H3
## inconsistent   casing

Links:

❌ Avoid
Click [here](./link.md)
See: https://example.com
[Link](./broken-link.md) <!-- Always verify links work -->

Code:

❌ Avoid

code without language specification


    Using indented code blocks

Images:

❌ Avoid
![](image.png)                    <!-- No alt text -->
![Click here](./img/diagram.png)  <!-- Poor alt text -->

🔍 Review Checklist​

Before submitting documentation, ensure:

Content Quality​

  • Front matter is complete and correct
  • Heading hierarchy is logical (H1 → H2 → H3)
  • All code blocks have language specifications
  • Links use descriptive text and work correctly
  • Images have meaningful alt text
  • Content follows the writing style guidelines

Technical Requirements​

  • File names use kebab-case
  • All internal links are tested
  • Images are optimized and properly located
  • Tables are properly formatted
  • Spelling and grammar are correct

Docusaurus Specific​

  • category.json files are present for folders
  • sidebar_position is set appropriately
  • No broken cross-references
  • Build runs without warnings

📚 Examples​

Complete Document Template​

---
sidebar_position: 1
title: Feature Name Standards
description: Guidelines for implementing feature name consistently
---

# Feature Name Standards

Brief overview of what this document covers and why it's important.

## When to Apply

Specific scenarios where these standards should be used.

## Guidelines

### Subsection 1

Clear, actionable rules with examples.

```javascript
// Code example showing correct implementation
const example = "properly formatted code";

Subsection 2​

More guidelines with context.

Examples​

Good Example​

// Show what good looks like
const goodImplementation = "clear and consistent";

What to Avoid​

// Show what to avoid
const badExample = "inconsistent_naming";

---

*This style guide ensures consistency across all documentation and makes it easier for contributors to create high-quality content that integrates seamlessly with our existing materials.*