https://github.com/jekwwer/markdown-workspace
A ready-to-use workspace for working with Markdown files. It features a devcontainer with custom VS Code settings and essential repo files, along with integrated formatting, linting, spell checking, link validation, pre-commit hooks, and automated release and dependency updates.
https://github.com/jekwwer/markdown-workspace
codespaces devcontainer development-environment markdown mkdocs mkdocs-material template vscode
Last synced: about 1 year ago
JSON representation
A ready-to-use workspace for working with Markdown files. It features a devcontainer with custom VS Code settings and essential repo files, along with integrated formatting, linting, spell checking, link validation, pre-commit hooks, and automated release and dependency updates.
- Host: GitHub
- URL: https://github.com/jekwwer/markdown-workspace
- Owner: Jekwwer
- License: mit
- Created: 2024-09-03T13:00:43.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-04-14T10:10:17.000Z (about 1 year ago)
- Last Synced: 2025-04-14T11:23:10.394Z (about 1 year ago)
- Topics: codespaces, devcontainer, development-environment, markdown, mkdocs, mkdocs-material, template, vscode
- Language: JavaScript
- Homepage: https://jekwwer.github.io/markdown-workspace/
- Size: 1.19 MB
- Stars: 1
- Watchers: 1
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
README
# 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.
[][open-in-codespaces]
## 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:
```bash
npm run format:write
```
For a formatting check without modifying files, run:
```bash
npm run format:check
```
### Linting
- **Lint Markdown** files with `markdownlint-cli`:
```bash
npm run lint:markdown
```
### Link Checking
- **Check Links** in Markdown files to prevent broken URLs:
```bash
npm run links:check
```
### Spell Checking
The task is automated and enforced using various tools.
To run spell checking manually, execute:
```bash
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:
```markdown
# 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:
```bash
npm run generate:toc
```
- After running the command, the `[[toc]]` placeholder will be replaced with a dynamically generated Table of Contents:
```markdown
# 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:
```bash
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:
```bash
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:
```bash
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:
```plaintext
https://.github.io//
```
**b. Automated Deployment with GitHub Actions:**
The project includes a GitHub Actions workflow ([`.github/workflows/deploy.yml`](.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:
```plaintext
https://.github.io//
```
**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][CONTRIBUTING] and check the [issues][issues] page.
## License 🛡️
This project is licensed under the [MIT License][LICENSE].
## Contact 📬
For questions, reach out via [evgenii.shiliaev@jekwwer.com][evgenii.shiliaev@jekwwer.com] or open an [issue][issues].
---
This document is based on a template by [Evgenii Shiliaev][evgenii-shiliaev-github],
licensed under [CC BY 4.0][jekwwer-markdown-docs-kit-license]. All additional content is licensed under [LICENSE][LICENSE].
[CONTRIBUTING]: CONTRIBUTING.md
[LICENSE]: LICENSE
[evgenii-shiliaev-github]: https://github.com/Jekwwer
[evgenii.shiliaev@jekwwer.com]: mailto:evgenii.shiliaev@jekwwer.com
[issues]: https://github.com/Jekwwer/markdown-workspace/issues
[jekwwer-markdown-docs-kit-license]: https://github.com/Jekwwer/markdown-docs-kit/blob/main/LICENSE
[open-in-codespaces]: https://codespaces.new/Jekwwer/markdown-workspace