Markdown Workspace

Project Overview 🚀

This repository is a comprehensive template for working with Markdown files. It comes equipped with tools for code formatting and linting, link validation, TOC generation, spell checking, a ready-to-use devcontainer, custom VS Code settings, essential repository files, automated releasing, and extensive documentation to support effective project management and customization.

Features ✨

• Devcontainer: Provides an Ubuntu-based environment with Python and Node support, custom VS Code settings and extensions, and a local PostgreSQL service.

• Formatting: Ensures consistent code style using Prettier, EditorConfig, and other tools.

• 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 checks before each commit.

• Release Automation: Manages releases automatically.

• Dependency Updates Automation: Keeps dependencies up-to-date via Dependabot.

Installation 📦

This setup is designed for GitHub Codespaces. Running locally has not been tested and may require additional configuration.

Usage 🛠️

The following scripts are available for managing and checking Markdown files:

Formatting

Most formatting tasks are automated and enforced using various tools. Feel free to adjust these settings for your project. The repository configurations are described in the [STYLEGUIDE.md][STYLEGUIDE].

• Markdown and Prettier-supported Files: The project uses Prettier for code formatting. Prettier automatically formats files in the editor when the following settings are enabled (already configured in the devcontainer):

  • editor.formatOnPaste: true
  • editor.formatOnSave: true
  • files.autoSave: onFocusChange

  To apply formatting to your code manually, run:

  npm run format:write

  For a formatting check without modifying files, run:

  npm run format:check

Linting

• Lint Markdown files with markdownlint-cli:

  npm run lint:markdown

Link Checking

• Check Links in Markdown files to prevent broken URLs:

  npm run links:check

Spell Checking

The task is automated and enforced using various tools.

To run spell checking manually, execute:

npm run spell:check

Adjust the cspell.json configuration file if needed.

Table of Contents Generation

• 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.

Live Preview with MkDocs

• Preview Markdown files as a website using MkDocs:

  npm run docs:serve

  • Visit http://localhost:8000 in your browser to see the documentation.

Build Documentation with MkDocs

• 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.

Deployment to GitHub Pages

• Deploy your documentation to GitHub Pages with MkDocs:

  1. Ensure your repository is set up with a mkdocs.yml configuration file and the documentation source files.

  2. 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 the gh-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 the main 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.

Contributing 👥

Contributions are welcome! Please read the Contributing Guidelines and check the issues page.

License 🛡️

This project is licensed under the MIT License.

Contact 📬

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.