Read the Docs Setup & Publish
Read the Docs simplifies documentation by automating building, versioning, and hosting of your docs for you.
Getting started
Read the Docs requires a repository (a.k.a. repo) with a minimum of:
- A specifically formatted
mkdocs.yml
YAML file - A
docs/
folder containing anindex.md
file
A sample mkdocs.yml
YAML file (YAML = YAML Ain't Markup Language)
site_name: My first readthedocs
theme: readthedocs
pages:
- Introduction: index.md
- Getting started: getting_started.md
Hands-on
GitHub Setup
- Sign into GitHub.
- Fork our sample repository, the button is in the top right corner of the repository.
Note (from the glossary): A fork is a Git concept of copying a repository from someone else's ownership to your ownership, all the while maintaining the history
Read the Docs Setup
- Log into readthdocs.org with your GitHub account.
- Click the Import a project button which will bring you to the Import a Repository menu.
- In the Import a repository menu select your forked repo with the + (plus) sign.
- Adjust the Name to something short and memorable for the documentation webpage name.
- Click Next on Project Details.
- Go to the Admin tab in the top right and then Advanced Settings on the left.
- Change Documentation type: to Mkdocs (Markdown).
- Click Save at the bottom.
Publish
- To see publishing progress go to the Build tab and find the latest build.
- When it says Build completed you can click the View Docs button to view those docs.
Discussion: Your new site
Take a look at the front page of your newly published readthedocs.org site. What advice might you suggest that you don't see there?