Read the Docs Modification & Troubleshooting
Hands-on: Modification
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.md
file with your neighbor's name.- Bonus: Use
**bold**
,*italics*
,- bullets
, and1. 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.
Demo: Troubleshooting
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.yaml
instead of the correct name,mkdocs.yml
. - Incorrectly spelled keys in
mkdocs.yml
. - Special characters in
pages:
names. - Incorrectly named or incorrectly placed
.md
files inmkdocs.yml
.
\ SORRY /
\ /
\ This page does /
] not exist yet. [ ,'|
] [ / |
]___ ___[ ,' |
] ]\ /[ [ |: |
] ] \ / [ [ |: |
] ] ] [ [ [ |: |
] ] ]__ __[ [ [ |: |
] ] ] ]\ _ /[ [ [ [ |: |
] ] ] ] (#) [ [ [ [ :===='
] ] ]_].nHn.[_[ [ [
] ] ] HHHHH. [ [ [
] ] / `HH("N \ [ [
]__]/ HHH " \[__[
] NNN [
] N/" [
] N H [
/ N \
/ q, \
/ \