{"id":16551214,"url":"https://github.com/michaelcurrin/mkdocs-quickstart","last_synced_at":"2025-10-28T18:31:26.621Z","repository":{"id":44721148,"uuid":"260767059","full_name":"MichaelCurrin/mkdocs-quickstart","owner":"MichaelCurrin","description":"Starter template for a MkDocs docs site on GH Pages - including CI","archived":false,"fork":false,"pushed_at":"2021-07-28T11:07:05.000Z","size":5704,"stargazers_count":19,"open_issues_count":12,"forks_count":4,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-02-01T17:11:11.945Z","etag":null,"topics":["demo","docs-site","gh-actions","github-actions","github-pages","mkdocs","mkdocs-quickstart","mkdocs-site","quickstart","starter","template","template-project","tutorial"],"latest_commit_sha":null,"homepage":"https://michaelcurrin.github.io/mkdocs-quickstart/","language":null,"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/MichaelCurrin.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-05-02T20:13:06.000Z","updated_at":"2024-11-02T16:00:35.000Z","dependencies_parsed_at":"2022-08-03T15:30:28.609Z","dependency_job_id":null,"html_url":"https://github.com/MichaelCurrin/mkdocs-quickstart","commit_stats":null,"previous_names":[],"tags_count":7,"template":true,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MichaelCurrin%2Fmkdocs-quickstart","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MichaelCurrin%2Fmkdocs-quickstart/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MichaelCurrin%2Fmkdocs-quickstart/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MichaelCurrin%2Fmkdocs-quickstart/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MichaelCurrin","download_url":"https://codeload.github.com/MichaelCurrin/mkdocs-quickstart/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238700280,"owners_count":19515896,"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":["demo","docs-site","gh-actions","github-actions","github-pages","mkdocs","mkdocs-quickstart","mkdocs-site","quickstart","starter","template","template-project","tutorial"],"created_at":"2024-10-11T19:36:38.776Z","updated_at":"2025-10-28T18:31:26.219Z","avatar_url":"https://github.com/MichaelCurrin.png","language":null,"readme":"# MkDocs Quickstart\n\u003e Starter template for a MkDocs docs site on GH Pages - including CI\n\n[![CI status](https://github.com/MichaelCurrin/mkdocs-quickstart/workflows/Deploy%20Docs/badge.svg)](https://github.com/MichaelCurrin/mkdocs-quickstart/actions)\n[![GitHub tag](https://img.shields.io/github/tag/MichaelCurrin/mkdocs-quickstart?include_prereleases=\u0026sort=semver)](https://github.com/MichaelCurrin/mkdocs-quickstart/releases/)\n[![License](https://img.shields.io/badge/License-MIT-blue)](#license)\n\n[![Made with Python](https://img.shields.io/badge/Python-\u003e%3D3.6-blue?logo=python\u0026logoColor=white)](https://python.org)\n[![Made with MkDocs](https://img.shields.io/badge/mkdocs-1-blue)](https://www.mkdocs.org/)\n[![CI - GH Actions](https://img.shields.io/badge/CI-GH_Actions-blue?logo=github-actions\u0026logoColor=white)](https://github.com/features/actions)\n\nA template, live demo and tutorial for how to set up a MkDocs docs site on GH Pages. Using GitHub Actions to automated deploys.\n\nMkDocs is a Python package when turns your docs directory and YAML config into a static website. No Python coding needed. Just Markdown and some light configuration including a theme choice and menu.\n\n\u003c!-- TODO When creating a new project copied from this template, you can delete this README.md and start over --\u003e\n\n\n## Purpose\n\nThis project provides low-code content-focused way to set up and host a markdown-based documentation site, with a professional look and themes. Built with MkDocs - a Python package which is a static site generator specializing in documentation.\n\nA GitHub Actions workflow is provided with this template so you can easily deploy to GitHub Pages too.\n\n\n## Preview\n\n\u003cdiv align=\"center\"\u003e\n\n[![Sample screenshot](/sample.png)](https://michaelcurrin.github.io/mkdocs-quickstart/ \"Sample screenshot\")\n\n\u003c/div\u003e\n\nThis template project is configured to use the _Read the Docs_ theme, as shown above. \n\nThus looks like the the [Read The Docs][] site, but without having to have to overhead of using Sphinx.\n\n[Read The Docs]: https://docs.readthedocs.io\n\nThis Read the Docs theme for MkDocs comes with MkDocs already, so you don't need to add to your dependencies. But you can switch to the MkDocs default or install and configure another theme.\n\nYou can switch to the default theme or install some others, based on the instructions in this template project.\n\n\n## How to use this project\n\n\u003cdiv align=\"center\"\u003e\n\n[![GH Pages](https://img.shields.io/badge/View_site-MkDocs_Quickstart-blue?style=for-the-badge)](https://michaelcurrin.github.io/mkdocs-quickstart/)\n\n[![Use this template](https://img.shields.io/badge/Generate-Use_this_template-2ea44f?style=for-the-badge)](https://github.com/MichaelCurrin/mkdocs-quickstart/generate)\n\n\u003c/div\u003e\n\n\n## Features\n\n- A **markdown-based** docs site which is easy to edit - see the content in the [docs](/docs/docs/) directory.\n- Easy to **configure** - see the short [mkdocs.yml](/docs/mkdocs.yml) file.\n- Use the configured theme or switch to another - no need to write HTML and CSS yourself.\n- Each theme comes with a navbar and you write YAML - Jekyll themes on GH Pages need you to write your own HTML often and each theme handles navbar its own way (sometimes not at all).\n- Uses a deploy pipeline on GH Actions to deploy a GH Pages site - the action actually runs GH Pages deploy command.\n- The static site output is **SEO-friendly**.\n- Built on Python but you don't need to write any Python code.\n\n### View live demo site\n\nThis project has a site deployed to GitHub Pages.\n\nPurposes of the site:\n\n- A live demo.\n- Content for a beginner-friendly tutorial on how to setup, run, deploy and customize a MkDocs project like this one.\n\n### Use this template\n\nThis repo also doubles as a template to create a new project from. Click the button at the top.\n\nChange the content and theme to suit your needs, based on the tutorial site or the MkDocs site.\n\nTo isolate the MkDocs flow from the rest of your code, you can put the configs and the `docs` folder of content inside the `docs` directory. That means you end up having `docs/docs`, which is okay. Just make sure you select the `/docs` directory when setting up GH Pages.\n\n\n## About MkDocs\n\n### Resources\n\n- Homepage: [mkdocs.org](http://www.mkdocs.org/)\n- Repo: [![mkdocs - mkdocs](https://img.shields.io/static/v1?label=mkdocs\u0026message=mkdocs\u0026color=blue\u0026logo=github)](https://github.com/mkdocs/mkdocs) [![stars - mkdocs](https://img.shields.io/github/stars/mkdocs/mkdocs?style=social)](https://github.com/mkdocs/mkdocs)\n- PyPI package: [mkdocs](https://pypi.org/project/mkdocs/)\n\n### Why MkDocs?\n\nIf you're new to MkDocs, look at the tutorial added on this project's site, otherwise go to the MkDocs homepage for documentation.\n\nThis project provides a way to write your docs in markdown and build a professional-looking docs site on top of it, without having to write HTML or CSS code and using a selection of themes. While MkDocs CLI has functionality to deploy from a local command-line, this project makes deploying effortless by using GitHub Actions to build and deploy the site to a `gh-pages` branch and GitHub Pages to serve the site.\n\nCompared with Jekyll and Docsify, I found the MkDocs code is much lighter to set up and changing themes is much easier than Jekyll. Also you get the benefits SEO which Docsify doesn't have. And it includes a search bar using JS.\n\n\n## Contributing\n\nSubmit an issue.\n\nOr submit a code change:\n\n1. Fork this project.\n2. Set up the project locally - follow the instructions on the live tutorial or in the [TL;DR](/docs/docs/tutorial/tldr.md) page of the local docs.\n3. Make any changes you want. Be sure to keep a copy of the original license in the repo.\n    - e.g. `cp LICENSE LICENSE-source`\n4. Create a Pull Request.\n\n\n## License\n\nReleased under [MIT](/LICENSE) by [@MichaelCurrin](https://github.com/MichaelCurrin).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmichaelcurrin%2Fmkdocs-quickstart","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmichaelcurrin%2Fmkdocs-quickstart","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmichaelcurrin%2Fmkdocs-quickstart/lists"}