{"id":28304060,"url":"https://github.com/readthedocs-examples/example-mkdocs-basic","last_synced_at":"2026-04-07T11:32:15.262Z","repository":{"id":41314836,"uuid":"509057798","full_name":"readthedocs-examples/example-mkdocs-basic","owner":"readthedocs-examples","description":"A basic MkDocs project for Read the Docs","archived":false,"fork":false,"pushed_at":"2025-06-16T10:40:13.000Z","size":29,"stargazers_count":20,"open_issues_count":4,"forks_count":69,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-06-16T11:40:37.663Z","etag":null,"topics":["example-project","mkdocs"],"latest_commit_sha":null,"homepage":"https://example-mkdocs-basic.readthedocs.io/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/readthedocs-examples.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2022-06-30T11:46:47.000Z","updated_at":"2025-02-27T08:33:57.000Z","dependencies_parsed_at":"2024-01-05T23:43:59.164Z","dependency_job_id":"61f5bdf3-90a5-49ef-9e14-7bc782b21f2b","html_url":"https://github.com/readthedocs-examples/example-mkdocs-basic","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/readthedocs-examples/example-mkdocs-basic","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/readthedocs-examples%2Fexample-mkdocs-basic","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/readthedocs-examples%2Fexample-mkdocs-basic/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/readthedocs-examples%2Fexample-mkdocs-basic/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/readthedocs-examples%2Fexample-mkdocs-basic/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/readthedocs-examples","download_url":"https://codeload.github.com/readthedocs-examples/example-mkdocs-basic/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/readthedocs-examples%2Fexample-mkdocs-basic/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31511605,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-07T03:10:19.677Z","status":"ssl_error","status_checked_at":"2026-04-07T03:10:13.982Z","response_time":105,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["example-project","mkdocs"],"created_at":"2025-05-24T00:11:58.086Z","updated_at":"2026-04-07T11:32:15.254Z","avatar_url":"https://github.com/readthedocs-examples.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"Example: Basic MkDocs project for Read the Docs\n===============================================\n\n[![Documentation Status](https://readthedocs.org/projects/example-mkdocs-basic/badge/?version=latest)](https://example-mkdocs-basic.readthedocs.io/en/latest/?badge=latest)\n\nThis example shows a basic MkDocs project with Read the Docs. You're encouraged to view it to get inspiration and copy \u0026 paste from the files in the source code. If you are using Read the Docs for the first time, have a look at the official [Read the Docs Tutorial](https://docs.readthedocs.io/en/stable/tutorial/index.html).\n\n📚 [docs/](https://github.com/readthedocs-examples/example-mkdocs-basic/blob/main/docs/)\u003cbr\u003e\nA basic MkDocs project lives in `docs/`, it was generated using MkDocs defaults. All the `*.md` make up sections in the documentation.\n\n⚙️ [.readthedocs.yaml](https://github.com/readthedocs-examples/example-mkdocs-basic/blob/main/.readthedocs.yaml)\u003cbr\u003e\nRead the Docs Build configuration is stored in `.readthedocs.yaml`.\n\n⚙️ [mkdocs.yml](https://github.com/readthedocs-examples/example-mkdocs-basic/blob/main/mkdocs.yml)\u003cbr\u003e\nA basic [MkDocs configuration](https://www.mkdocs.org/user-guide/configuration/) is stored here, including a few extensions for MkDocs and Markdown. Add your own configurations here, such as extensions and themes. Remember that many extensions and themes require additional Python packages to be installed.\n\n📍 [docs/requirements.txt](https://github.com/readthedocs-examples/example-mkdocs-basic/blob/main/docs/requirements.txt) and [docs/requirements.in](https://github.com/readthedocs-examples/example-mkdocs-basic/blob/main/docs/requirements.in)\u003cbr\u003e\nPython dependencies are [pinned](https://docs.readthedocs.io/en/latest/guides/reproducible-builds.html) (uses [pip-tools](https://pip-tools.readthedocs.io/en/latest/)) here. Make sure to add your Python dependencies to `requirements.txt` or if you choose [pip-tools](https://pip-tools.readthedocs.io/en/latest/), edit `docs/requirements.in` and remember to run to run `pip-compile docs/requirements.in`.\n\n💡 [docs/api.md](https://github.com/readthedocs-examples/example-mkdocs-basic/blob/main/docs/api.md)\u003cbr\u003e\nWe add our example Python module `lumache` in order to auto-generate an API reference. To do this, we use the `:::` syntax, you can read more in the [mkdocstrings documentation](https://mkdocstrings.github.io/).\n\n💡 [docs/usage.md](https://github.com/readthedocs-examples/example-mkdocs-basic/blob/main/docs/usage.md)\u003cbr\u003e\nWe also include some direct links to a function from the API reference, as well as embedding documentation for the example function `lumache.get_random_recipe`. This functionality is also from the [mkdocstrings](https://mkdocstrings.github.io/python/) extension.\n\n💡 [lumache.py](https://github.com/readthedocs-examples/example-mkdocs-basic/blob/main/lumache.py)\u003cbr\u003e\nAPI docs are generated for this example Python module - they use *docstrings* directly in the documentation, notice how this shows up in the rendered documentation. We use the [Sphinx convention](https://pythonhosted.org/an_example_pypi_project/sphinx.html#function-definitions) for docstrings, however you are free to edit `mkdocs.yml` to change this option to `google` or `numpy`.\n\n🔢 Git tags versioning\u003cbr\u003e\nWe use a basic versioning mechanism by adding a git tag for every release of the example project. All releases and their version numbers are visible on\n[example-mkdocs-basic.readthedocs.io](https://example-mkdocs-basic.readthedocs.io/en/latest/).\n\n📜 [README.md](https://github.com/readthedocs-examples/example-mkdocs-basic/blob/main/README.md)\u003cbr\u003e\nContents of this `README.md` are visible on Github and included on [the documentation index page](https://example-mkdocs-basic.readthedocs.io/en/latest/) (Don\\'t Repeat Yourself).\n\n⁉️ Questions / comments\u003cbr\u003e\nIf you have questions related to this example, feel free to can ask them as a Github issue [here](https://github.com/readthedocs-examples/example-mkdocs-basic/issues).\n\n\nExample Project usage\n---------------------\n\nThis project has a standard MkDocs layout which is built by Read the Docs almost the same way that you would build it locally (on your own laptop!).\n\nYou can build and view this documentation project locally - we recommend that you activate [a local Python virtual environment first](https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/#creating-a-virtual-environment):\n\n```console\n# Install required Python dependencies (MkDocs etc.)\npip install -r docs/requirements.txt\n\n# Run the mkdocs development server\nmkdocs serve\n```\n\nUsing the example in your own project\n-------------------------------------\n\nIf you are new to Read the Docs, you may want to refer to the [Read the Docs User documentation](https://docs.readthedocs.io/).\n\nIf you are copying this code in order to get started with your documentation, you need to:\n\n1. place your `docs/` folder alongside your Python project. If you are starting a new project, you can adapt the `pyproject.toml` example configuration.\n1. use your existing project repository or create a new repository on Github, GitLab, Bitbucket or another host supported by Read the Docs.\n1. copy `mkdocs.yml`, `.readthedocs.yaml` and the `docs/` folder into your project.\n1. customize all the files, replacing example contents.\n1. Rebuild the documenation locally to see that it works.\n1. *Finally*, register your project on Read the Docs, see [Importing Your Documentation](https://docs.readthedocs.io/en/stable/intro/import-guide.html).\n\n\nRead the Docs tutorial\n----------------------\n\nTo get started with Read the Docs, you may also refer to the [Read the Docs tutorial](https://docs.readthedocs.io/en/stable/tutorial/). It provides a full walk-through of building an example project similar to the one in this repository.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Freadthedocs-examples%2Fexample-mkdocs-basic","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Freadthedocs-examples%2Fexample-mkdocs-basic","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Freadthedocs-examples%2Fexample-mkdocs-basic/lists"}