This repository is a comprehensive template for working with Markdown files, equipped with tools for formatting, linting, spell checking, link validation, and more. Ideal for documentation projects, blogs, or any Markdown-heavy projects.
- Formatting: Maintains consistent style across Markdown files using Prettier.
- Linting: Enforces Markdown standards and best practices with markdownlint.
- Link Checking: Validates internal and external links to prevent broken URLs.
- Spell Checking: Detects and highlights spelling errors in Markdown files.
- Table of Contents (TOC): Automatically generates and updates TOCs for large files. (Note: Redundant if using MkDocs, as it generates TOCs automatically.)
- Live Preview: Provides a local preview of documentation as a website using MkDocs.
- Static Site Generation: Converts Markdown files into a fully functional static website with MkDocs.
- Automated Deployment: Deploys documentation to GitHub Pages via GitHub Actions or the
mkdocs gh-deploy
command. - Pre-commit Hooks: Automates quality assurance checks before each commit with pre-commit.
This setup is designed for GitHub Codespaces. Running locally has not been tested and may require additional configuration.
The following scripts are available for managing and checking Markdown files:
-
Run Prettier to format Markdown files:
npm run format:code
For a formatting check without modifying, run:
npm run format:check
-
Lint Markdown files with
markdownlint-cli
:npm run lint:markdown
-
Check Links in Markdown files to prevent broken URLs:
npm run check:links
-
Run Spell Check on Markdown files:
npm run check:spelling
-
Generate or Update TOC in Markdown files containing the
[[toc]]
placeholder:Add the
[[toc]]
placeholder where you want the TOC to appear in your Markdown files. For example:# My Project ## Table of Contents [[toc]] ## Section 1 Content for section 1. ### Subsection 1.1 Content for subsection 1.1. ## Section 2 Content for section 2.
Then run the following command to generate or update the TOC:
npm run generate:toc
-
After running the command, the
[[toc]]
placeholder will be replaced with a dynamically generated Table of Contents:# My Project ## Table of Contents - [Section 1](#section-1) - [Subsection 1.1](#subsection-11) - [Section 2](#section-2) ## Section 1 Content for section 1. ### Subsection 1.1 Content for subsection 1.1. ## Section 2 Content for section 2.
-
Preview Markdown files as a website using MkDocs:
npm run docs:serve
- Visit
http://localhost:8000
in your browser to see the documentation.
- Visit
-
Build static site from Markdown files using MkDocs:
To create a static website from your documentation, run the following command:
npm run docs:build
This command will generate a
site
directory containing the built static files. You can serve these files with any web server or use them for deployment.
-
Deploy your documentation to GitHub Pages with MkDocs:
-
Ensure your repository is set up with a
mkdocs.yml
configuration file and the documentation source files. -
Deploy your documentation using one of the following methods:
a. Manual Deployment: Run the following command to manually deploy the documentation:
npm run docs:deploy
This command will:
- Build the static site.
- Push the
site
directory to thegh-pages
branch of your repository.
After deployment, your documentation will be available at:
https://<username>.github.io/<repository-name>/
b. Automated Deployment with GitHub Actions: The project includes a GitHub Actions workflow (
.github/workflows/deploy.yml
) that automatically deploys the documentation to GitHub Pages whenever changes are pushed to themain
branch.After deployment, your documentation will be available at the
gh-pages
branch of your repository:https://<username>.github.io/<repository-name>/
Note: Ensure your repository settings have GitHub Pages enabled, and the source is set to the
gh-pages
branch. -
Contributions are welcome! Please read the Contributing Guidelines and check the issues page.
This project is licensed under the MIT License.
For questions, reach out via [email protected] or open an issue.
This document is based on a template by Evgenii Shiliaev, licensed under CC BY 4.0. All additional content is licensed under LICENSE.