Skip to content
/ markdown-workspace Public template

A comprehensive template for working with Markdown files, equipped with tools for formatting, linting, spell checking, link validation, and more.

License

Notifications You must be signed in to change notification settings

Jekwwer/markdown-workspace

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

Markdown Workspace

GitHub Release GitHub Release Date GitHub commits since latest release Libraries.io dependency status for GitHub repo Issues Maintained GitHub License

Project Overview πŸš€

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.

Features ✨

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

Installation πŸ“¦

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

Open in GitHub Codespaces

Usage πŸ› οΈ

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

Formatting

  • Run Prettier to format Markdown files:

    npm run format:code

    For a formatting check without modifying, 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 check:links

Spell Checking

  • Run Spell Check on Markdown files:

    npm run check:spelling

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.