loading...
Cover image for Quick Github Tip: View Your Documentation Changes Before Publishing

Quick Github Tip: View Your Documentation Changes Before Publishing

alli profile image Alli Teration ・2 min read

Have you ever updated documentation for a GitHub repository only to discover after you pushed your changes to production that you misused some markdown and now your documentation looks weird? Maybe it's just me, but I didn't figure this out until after doing it the hard way one too many times.

You can see how your documentation looks by switching to your branch in GitHub and then viewing the documentation page you updated. GitHub displays markdown files (.md extension) as styled text, not as code. Which means they'll show the stylized text for whatever branch you're on. In the below image, I'm in the main branch so I won't see my updates:

A screenshot from GitHub: There is an arrow pointing to the branch selector, where the main branch is selected.

To switch branches, find the dropdown that has the name of the current branch you're looking at in the upper left hadn't corner. Click on it and find your branch with your documentation changes and select it. Then go to the documentation file you updated and check out your changes!

Here I've switched to my branch and I can see my documentation changes:

A screenshot from GitHub: There is an arrow pointing to the branch selector, where a branch that's not the main branch is selected. You can see some documentation below the branch selector.

Now you don't need to merge your code every time you try and fix some documentation formatting. Get it looking good in your branch first, and merge when it's ready to go. This can also be helpful when code reviewing a peer's documentation change.

Cover Image: A top-down stock photo of a man writing in a notebook next to a MacBook.

Discussion

pic
Editor guide