Read the Docs Modification & Troubleshooting
You'll need a copy of your docs tied to your GitHub repo if you don't already have one.
- Sign into GitHub.
- Go to your Forked version of our sample repository. Forks of an original repo can be found by clicking the number next to Fork in the top right of the repo.
- Click Clone or Download and then Open in Desktop.
- Within GitHub Desktop there should be an Open in Visual Studio Code button. Click that button.
- Within Visual Studio Code, update the
contributors.mdfile with your neighbor's name.
- Bonus: Use
- bullets, and
1. numbered lists. Remember the Markdown Cheatsheet.
- Bonus: Use
Hands-on: Add a readthedocs.org maintainer
- Log into readthdocs.org with your GitHub account.
- Click your name in the top right corner to go to My Projects.
- Click your Read the Docs Project.
- Click the Admin tab.
- On the left menu click Maintainers.
- Here you can add maintainers to your Read the Docs Project by typing in their Read the Docs User account name.
Documentation site-breaking problems are usually confined to the
mkdocs.yml YAML file. To publish new content:
- Make and save edits.
- Stage your edits.
- Commit your edits.
- Push your commit.
- Go to your readthedocs.org Project inside the Builds tab.
- Click on the newest build.
- Watch your docs build in real-time.
Note: If your edited docs look like they haven't changed even though you know you've changed them and the build has completed, try a different browser or an "Incognito Browser" mode to see newer edits.
Discussion: What are some site-breaking things you can guess?
Problems I have run into:
- Incorrectly named
mkdocs.yamlinstead of the correct name,
- Incorrectly spelled keys in
- Special characters in
- Incorrectly named or incorrectly placed
\ SORRY / \ / \ This page does / ] not exist yet. [ ,'| ] [ / | ]___ ___[ ,' | ] ]\ /[ [ |: | ] ] \ / [ [ |: | ] ] ] [ [ [ |: | ] ] ]__ __[ [ [ |: | ] ] ] ]\ _ /[ [ [ [ |: | ] ] ] ] (#) [ [ [ [ :====' ] ] ]_].nHn.[_[ [ [ ] ] ] HHHHH. [ [ [ ] ] / `HH("N \ [ [ ]__]/ HHH " \[__[ ] NNN [ ] N/" [ ] N H [ / N \ / q, \ / \