{"id":25098175,"url":"https://github.com/jekwwer/markdown-workspace","last_synced_at":"2025-04-19T12:16:45.348Z","repository":{"id":262263722,"uuid":"851633748","full_name":"Jekwwer/markdown-workspace","owner":"Jekwwer","description":"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.","archived":false,"fork":false,"pushed_at":"2025-04-14T10:10:17.000Z","size":1251,"stargazers_count":1,"open_issues_count":1,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-14T11:23:10.394Z","etag":null,"topics":["codespaces","devcontainer","development-environment","markdown","mkdocs","mkdocs-material","template","vscode"],"latest_commit_sha":null,"homepage":"https://jekwwer.github.io/markdown-workspace/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Jekwwer.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":"jekwwer","buy_me_a_coffee":"jekwwer","ko_fi":"jekwwer","liberapay":"jekwwer","open_collective":"jekwwer","patreon":"jekwwer"}},"created_at":"2024-09-03T13:00:43.000Z","updated_at":"2025-04-14T10:04:45.000Z","dependencies_parsed_at":"2024-11-11T14:25:05.339Z","dependency_job_id":"e527b761-ede3-40d9-91cc-3f8a8e60e8a2","html_url":"https://github.com/Jekwwer/markdown-workspace","commit_stats":null,"previous_names":["jekwwer/markdown-template","jekwwer/markdown-workspace"],"tags_count":19,"template":true,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Jekwwer%2Fmarkdown-workspace","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Jekwwer%2Fmarkdown-workspace/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Jekwwer%2Fmarkdown-workspace/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Jekwwer%2Fmarkdown-workspace/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Jekwwer","download_url":"https://codeload.github.com/Jekwwer/markdown-workspace/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249692622,"owners_count":21311407,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["codespaces","devcontainer","development-environment","markdown","mkdocs","mkdocs-material","template","vscode"],"created_at":"2025-02-07T18:19:57.253Z","updated_at":"2025-04-19T12:16:45.331Z","avatar_url":"https://github.com/Jekwwer.png","language":"JavaScript","funding_links":["https://github.com/sponsors/jekwwer","https://buymeacoffee.com/jekwwer","https://ko-fi.com/jekwwer","https://liberapay.com/jekwwer","https://opencollective.com/jekwwer","https://patreon.com/jekwwer"],"categories":[],"sub_categories":[],"readme":"# Markdown Workspace\n\n![GitHub Release](https://img.shields.io/github/v/release/Jekwwer/markdown-workspace?logo=github\u0026link=https%3A%2F%2Fgithub.com%2FJekwwer%2Fmarkdown-workspace%2Freleases%2Flatest)\n![GitHub Release Date](https://img.shields.io/github/release-date/Jekwwer/markdown-workspace?link=https%3A%2F%2Fgithub.com%2FJekwwer%2Fmarkdown-workspace%2Freleases%2Flatest)\n![GitHub commits since latest release](https://img.shields.io/github/commits-since/Jekwwer/markdown-workspace/latest?link=https%3A%2F%2Fgithub.com%2FJekwwer%2Fmarkdown-workspace%2Freleases%2Flatest)\n![Libraries.io dependency status for GitHub repo](https://img.shields.io/librariesio/github/Jekwwer/markdown-workspace?logo=librariesdotio\u0026logoColor=%23FFFFFF)\n![Issues](https://img.shields.io/github/issues/Jekwwer/markdown-workspace?logo=github\u0026link=https%3A%2F%2Fgithub.com%2FJekwwer%2Fmarkdown-workspace%2Fissues)\n![Maintained](https://img.shields.io/maintenance/yes/2025)\n![GitHub License](https://img.shields.io/github/license/Jekwwer/markdown-workspace?link=https%3A%2F%2Fgithub.com%2FJekwwer%2Fmarkdown-workspace%2Fblob%2Fmain%2FLICENSE)\n\n## Project Overview 🚀\n\nThis repository is a comprehensive template for working with Markdown files.\nIt comes equipped with tools for code formatting and linting, link validation, TOC generation, spell checking,\na ready-to-use devcontainer, custom VS Code settings, essential repository files, automated releasing,\nand extensive documentation to support effective project management and customization.\n\n## Features ✨\n\n- **Devcontainer:**\n  Provides an Ubuntu-based environment with Python and Node support, custom VS Code settings and extensions,\n  and a local PostgreSQL service.\n\n- **Formatting:**\n  Ensures consistent code style using **Prettier**, **EditorConfig**, and other tools.\n\n- **Linting:**\n  Enforces Markdown standards and best practices with **markdownlint**.\n\n- **Link Checking:**\n  Validates internal and external links to prevent broken URLs.\n\n- **Spell Checking:**\n  Detects and highlights spelling errors in Markdown files.\n\n- **Table of Contents (TOC):**\n  Automatically generates and updates TOCs for large files.\n  _(Note: Redundant if using MkDocs, as it generates TOCs automatically.)_\n\n- **Live Preview:**\n  Provides a local preview of documentation as a website using **MkDocs**.\n\n- **Static Site Generation:**\n  Converts Markdown files into a fully functional static website with MkDocs.\n\n- **Automated Deployment:**\n  Deploys documentation to GitHub Pages via GitHub Actions or the `mkdocs gh-deploy` command.\n\n- **Pre-commit Hooks:**\n  Automates quality checks before each commit.\n\n- **Release Automation:**\n  Manages releases automatically.\n\n- **Dependency Updates Automation:**\n  Keeps dependencies up-to-date via **Dependabot**.\n\n## Installation 📦\n\nThis setup is designed for **GitHub Codespaces**.\nRunning locally has **not been tested** and may require additional configuration.\n\n[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)][open-in-codespaces]\n\n## Usage 🛠️\n\nThe following scripts are available for managing and checking Markdown files:\n\n### Formatting\n\nMost formatting tasks are automated and enforced using various tools.\nFeel free to adjust these settings for your project.\nThe repository configurations are described in the [`STYLEGUIDE.md`][STYLEGUIDE].\n\n- **Markdown and Prettier-supported Files:**\n  The project uses **Prettier** for code formatting.\n  **Prettier** automatically formats files in the editor when the following settings are enabled\n  (already configured in the devcontainer):\n\n  - `editor.formatOnPaste`: true\n  - `editor.formatOnSave`: true\n  - `files.autoSave`: onFocusChange\n\n  To apply formatting to your code manually, run:\n\n  ```bash\n  npm run format:write\n  ```\n\n  For a formatting check without modifying files, run:\n\n  ```bash\n  npm run format:check\n  ```\n\n### Linting\n\n- **Lint Markdown** files with `markdownlint-cli`:\n\n  ```bash\n  npm run lint:markdown\n  ```\n\n### Link Checking\n\n- **Check Links** in Markdown files to prevent broken URLs:\n\n  ```bash\n  npm run links:check\n  ```\n\n### Spell Checking\n\nThe task is automated and enforced using various tools.\n\nTo run spell checking manually, execute:\n\n```bash\nnpm run spell:check\n```\n\nAdjust the `cspell.json` configuration file if needed.\n\n### Table of Contents Generation\n\n- **Generate or Update TOC** in Markdown files containing the `[[toc]]` placeholder:\n\n  Add the `[[toc]]` placeholder where you want the TOC to appear in your Markdown files. For example:\n\n  ```markdown\n  # My Project\n\n  ## Table of Contents\n\n  [[toc]]\n\n  ## Section 1\n\n  Content for section 1.\n\n  ### Subsection 1.1\n\n  Content for subsection 1.1.\n\n  ## Section 2\n\n  Content for section 2.\n  ```\n\n  Then run the following command to generate or update the TOC:\n\n  ```bash\n  npm run generate:toc\n  ```\n\n- After running the command, the `[[toc]]` placeholder will be replaced with a dynamically generated Table of Contents:\n\n  ```markdown\n  # My Project\n\n  ## Table of Contents\n\n  - [Section 1](#section-1)\n    - [Subsection 1.1](#subsection-11)\n  - [Section 2](#section-2)\n\n  ## Section 1\n\n  Content for section 1.\n\n  ### Subsection 1.1\n\n  Content for subsection 1.1.\n\n  ## Section 2\n\n  Content for section 2.\n  ```\n\n### Live Preview with MkDocs\n\n- **Preview Markdown files** as a website using MkDocs:\n\n  ```bash\n  npm run docs:serve\n  ```\n\n  - Visit `http://localhost:8000` in your browser to see the documentation.\n\n### Build Documentation with MkDocs\n\n- **Build static site** from Markdown files using MkDocs:\n\n  To create a static website from your documentation, run the following command:\n\n  ```bash\n  npm run docs:build\n  ```\n\n  This command will generate a `site` directory containing the built static files.\n  You can serve these files with any web server or use them for deployment.\n\n### Deployment to GitHub Pages\n\n- **Deploy your documentation** to GitHub Pages with MkDocs:\n\n  1. Ensure your repository is set up with a `mkdocs.yml` configuration file and the documentation source files.\n\n  2. Deploy your documentation using one of the following methods:\n\n     **a. Manual Deployment:**\n     Run the following command to manually deploy the documentation:\n\n     ```bash\n     npm run docs:deploy\n     ```\n\n     This command will:\n\n     - Build the static site.\n     - Push the `site` directory to the `gh-pages` branch of your repository.\n\n     After deployment, your documentation will be available at:\n\n     ```plaintext\n     https://\u003cusername\u003e.github.io/\u003crepository-name\u003e/\n     ```\n\n     **b. Automated Deployment with GitHub Actions:**\n     The project includes a GitHub Actions workflow ([`.github/workflows/deploy.yml`](.github/workflows/deploy.yml))\n     that automatically deploys the documentation to GitHub Pages whenever changes are pushed to the `main` branch.\n\n     After deployment, your documentation will be available at the `gh-pages` branch of your repository:\n\n     ```plaintext\n     https://\u003cusername\u003e.github.io/\u003crepository-name\u003e/\n     ```\n\n  **Note:** Ensure your repository settings have GitHub Pages enabled, and the source is set to the `gh-pages` branch.\n\n## Contributing 👥\n\nContributions are welcome! Please read the [Contributing Guidelines][CONTRIBUTING] and check the [issues][issues] page.\n\n## License 🛡️\n\nThis project is licensed under the [MIT License][LICENSE].\n\n## Contact 📬\n\nFor questions, reach out via [evgenii.shiliaev@jekwwer.com][evgenii.shiliaev@jekwwer.com] or open an [issue][issues].\n\n---\n\nThis document is based on a template by [Evgenii Shiliaev][evgenii-shiliaev-github],\nlicensed under [CC BY 4.0][jekwwer-markdown-docs-kit-license]. All additional content is licensed under [LICENSE][LICENSE].\n\n[CONTRIBUTING]: CONTRIBUTING.md\n[LICENSE]: LICENSE\n[evgenii-shiliaev-github]: https://github.com/Jekwwer\n[evgenii.shiliaev@jekwwer.com]: mailto:evgenii.shiliaev@jekwwer.com\n[issues]: https://github.com/Jekwwer/markdown-workspace/issues\n[jekwwer-markdown-docs-kit-license]: https://github.com/Jekwwer/markdown-docs-kit/blob/main/LICENSE\n[open-in-codespaces]: https://codespaces.new/Jekwwer/markdown-workspace\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjekwwer%2Fmarkdown-workspace","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjekwwer%2Fmarkdown-workspace","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjekwwer%2Fmarkdown-workspace/lists"}