Skip to content

MkDocs Site Operations & Utilization Guide

Detailed explanation of content enrichment and operational methods after creating a basic MkDocs site.

Prerequisites

What You Can Achieve

  • Multi-Page Deployment

    Organize rich content with systematic site structure

  • Efficient Update Workflow

    Build mechanisms for continuous content updates

  • Team Operation Support

    Content creation and review flow for multiple contributors

  • Content Strategy

    Build a site that provides value to readers

1. Creating Multiple Pages

Basic Page Addition

Create new Markdown files to add pages to your site.

① File Creation

# Create new files in the docs directory
touch docs/getting-started.md
touch docs/tutorial.md
touch docs/reference.md

② Update mkdocs.yml

site_name: My Documentation

theme:
  name: material
  language: ja

nav:
  - Home: index.md
  - Getting Started: getting-started.md
  - Tutorial: tutorial.md
  - Reference: reference.md
  - About: about.md

Creating Hierarchical Structure

To create a more complex site structure, use directories for hierarchy.

① Directory Structure

docs/
├── index.md
├── getting-started/
│   ├── index.md
│   ├── installation.md
│   └── quickstart.md
├── tutorial/
│   ├── index.md
│   ├── basic.md
│   └── advanced.md
└── reference/
    ├── index.md
    ├── api.md
    └── config.md

② Corresponding mkdocs.yml

nav:
  - Home: index.md
  - Getting Started:
    - getting-started/index.md
    - Installation: getting-started/installation.md
    - Quick Start: getting-started/quickstart.md
  - Tutorial:
    - tutorial/index.md
    - Basics: tutorial/basic.md
    - Advanced: tutorial/advanced.md
  - Reference:
    - reference/index.md
    - API: reference/api.md
    - Configuration: reference/config.md

2. Content Creation Best Practices

Article Structure Template

A template for creating consistent articles.

# Article Title

Brief overview of the article in 1-2 lines

## Prerequisites

- Required knowledge and preparation
- Previous articles to reference

## What You Can Achieve

Clearly state what can be learned from this article

## Steps

### 1. First Step

Provide clear and understandable procedures

### 2. Next Step

Utilize code blocks and illustrations

## Summary

- What was achieved
- Guide to next steps

## Related Articles

- [Related Article 1](/MkDocs/link1/)
- [Related Article 2](/MkDocs/link2/)

Markdown Utilization Tips

Appropriate Heading Structure

# h1 - Page Title (only one)
## h2 - Major Section
### h3 - Subsection  
#### h4 - Minor Section

Utilizing Code Blocks

# Bash command example
mkdocs serve

# YAML configuration example
site_name: My Site
theme:
  name: material

# Python code example
def hello():
    print("Hello, World!")

Admonition Boxes

!!! note "Note"
    Supplementary information or notes

!!! tip "Tip"
    Useful usage tips

!!! warning "Warning"
    Important warnings

!!! success "Success"
    Achievements and accomplishments

3. Efficient Update Workflow

Daily Update Operations

① From Draft to Publication

# 1. Create a new article
touch docs/new-article.md

# 2. Write and review locally
mkdocs serve

# 3. Commit changes
git add .
git commit -m "Add new article about XXX"

# 4. Deploy to GitHub Pages
mkdocs gh-deploy

② Updating Articles

# After editing existing article
git add docs/existing-article.md
git commit -m "Update article: add troubleshooting section"
mkdocs gh-deploy

Content Planning Cycle

Monthly Review

  • Check access analytics (see Analytics Setup)
  • Identify missing content
  • List improvement points for existing articles

Content Calendar

## March 2024 Plan

### Week 1
- [ ] Revise tutorial articles
- [ ] Write new feature explanation article

### Week 2  
- [ ] Enrich FAQ collection
- [ ] Organize links in existing articles

### Week 3
- [ ] Add use case articles
- [ ] Add images and diagrams

### Week 4
- [ ] Monthly review and next month's plan

4. Team Operation Workflow

Branching Strategy

Git workflow for multi-person operations:

# 1. Create new branch for article
git checkout -b feature/new-tutorial

# 2. Create and edit article
# Create docs/tutorial/new-feature.md

# 3. Local review
mkdocs serve

# 4. Create pull request
git add .
git commit -m "Add tutorial for new feature"
git push origin feature/new-tutorial

Review Process

Pull Request Template

## Changes

- [ ] New article addition
- [ ] Existing article update
- [ ] Configuration file changes

## Checklist

- [ ] Local build verified
- [ ] Links work correctly
- [ ] Typos checked
- [ ] Images display properly

## Related Issue

Closes #123

Article Creation Guidelines

Writing Style & Notation Consistency

# Style Guide

## Basic Policy
- Use polite form consistently
- Explain technical terms on first use
- Enclose commands in `backticks`

## Notation Rules
- GitHub (× Github)
- JavaScript (× Javascript)  
- Markdown (× markdown)

5. Content Strategy

Site Structure Design

Information Architecture

Home
├── Getting Started (for new users)
│   ├── Overview & Features
│   ├── Installation
│   └── Quick Start
├── Tutorial (step-by-step learning)
│   ├── Basics
│   ├── Practice
│   └── Advanced
├── Guide (purpose-specific explanations)
│   ├── Deployment
│   ├── Customization
│   └── Troubleshooting
└── Reference (dictionary-style information)
    ├── API Specifications
    ├── Configuration Options
    └── FAQ

SEO Optimization

Metadata Configuration

Set appropriate metadata for each article:

# mkdocs.yml
plugins:
  - meta

extra:
  social:
    - icon: fontawesome/brands/github
      link: https://github.com/username

---
title: Specific and Searchable Title
description: Article summary (within 150 characters)
keywords: mkdocs, github pages, documentation
---

# Article Content

Appropriate links to related articles:
- [Previous Step](/MkDocs/previous-step/)
- [Basic Configuration](/basics/configuration)
- [Troubleshooting](/../troubleshooting)

6. Real Operation Examples

Use Cases on This Site

📝 Technical Documentation

📚 Knowledge Base

🎨 Advanced Customization Examples

  • Analytics: Google Analytics Setup - GA4 implementation and privacy compliance
  • UI/UX: Implemented 3-column grid layout, dark mode, and search functionality

Keys to Success

  1. Continuous Updates: Regular updates at least once a week
  2. User-First: Prioritize solving readers' problems
  3. Quality Focus: Publish only verified and accurate information
  4. SEO Awareness: Searchable titles and metadata

Summary

Operating an MkDocs site requires continuous content enrichment after basic construction.

For Effective Operation: - ✅ Planned content creation - ✅ Unified workflow
- ✅ Systematized team operations - ✅ User-centered information design

By continuously providing valuable content, you can grow your site into one that benefits many people.