Preview README.md before you push, then verify GitHub-specific rendering after publishing. Check headings, tables, code, relative links, images, and task lists.
Contents (7)
A README can look fine as raw Markdown and still break once it is rendered on GitHub.
The useful distinction is between pre-publish Markdown checking and final GitHub verification.
A general Markdown viewer can catch broken headings, tables, lists, and code fences before you push. But GitHub uses GitHub Flavored Markdown (GFM) plus GitHub-specific handling, so a local or browser preview should not be treated as a perfect GitHub emulator.
What to check before you push
For most README files, the highest-value checks are:
- heading hierarchy
- fenced code blocks
- tables
- links
- images
- task lists
A README with only paragraphs is hard to break. Problems become more likely as you add setup commands, nested lists, tables, screenshots, badges, and relative links.
Preview first, verify on GitHub second
A practical workflow is:
- open the README in a Markdown viewer
- fix obvious Markdown syntax problems
- push the file to the repository
- check the final rendering on GitHub
oka-project's Markdown Viewer can preview a local .md file in the browser. It is free, requires no account, and processes the file in the browser rather than uploading the document body to a conversion server.
The tool interface is currently Japanese.
Use it as a first-pass preview, not as a complete GitHub rendering simulator.
1. Check heading hierarchy
README structure is easier to review when rendered.
# Project name
## Installation
### Requirements
## Usage
Look for skipped levels, overly fragmented sections, or a document that has too many top-level headings.
A simple structure such as:
Overview
Installation
Usage
Configuration
Troubleshooting
is often easier to scan than a README with many small sections at the same level.
2. Make sure code fences close correctly
README files often contain installation commands or configuration examples.
```bash
npm install
npm run dev
```
If the closing fence is missing, everything after it may render as code.
This is one of the easiest problems to catch in a preview because the visual break is obvious.
3. Check tables for GFM syntax issues
GitHub Flavored Markdown supports tables.
| Item | Value |
| --- | --- |
| OS | Windows / macOS |
| License | MIT |
Common problems include:
- header and delimiter rows with different column counts
- unescaped pipe characters inside cells
- malformed delimiter rows
The GFM specification requires the header row and delimiter row to contain the same number of cells.
For table-specific troubleshooting, see Why Markdown Tables Break and How to Fix Them.
4. Treat task lists as GitHub-specific behavior
GitHub supports task lists such as:
- [x] Initial setup
- [ ] Add documentation
- [ ] Publish release
A general Markdown renderer may display the checkboxes, but GitHub can add behavior and UI around task lists that a generic viewer does not reproduce.
That is why the final check should happen on GitHub.
5. Relative links need the repository context
A README often links to files inside the same repository.
[Setup guide](docs/setup.md)
A local viewer can confirm that the Markdown syntax is valid, but it cannot fully verify whether the path resolves correctly in the repository.
GitHub's documentation explains that relative links and image paths are resolved in the context of the current branch and repository structure.
The same applies to relative images.
Check these on GitHub after the README is in place:
- file path
- capitalization
- current branch
- moved or renamed files
- relative image paths
Why a generic Markdown preview can differ from GitHub
GitHub uses GitHub Flavored Markdown.
GFM builds on CommonMark and adds extensions such as:
- tables
- task lists
- strikethrough
- autolinks
GitHub.com also performs additional processing after Markdown is converted to HTML.
That creates two separate questions:
Is the Markdown structurally valid?
A general viewer can help answer this.
Does it render and behave correctly on GitHub?
Only the final GitHub page can answer that reliably.
A simple pre-publish checklist
Before pushing the README, check:
- one clear document title
- heading levels are logical
- code fences open and close correctly
- tables render as tables
- link text is meaningful
- image paths look correct
- task-list syntax is valid
Then, after pushing:
- relative links open the expected files
- images load
- GFM-specific elements render correctly
- heading links work as expected
- the README is readable on the repository page
Previewing an unpublished README
If the README includes private setup notes, internal URLs, or unreleased project details, check how the preview tool handles the file.
Some online tools upload the file to a server. Others process it locally in the browser.
oka-project's Markdown Viewer processes the Markdown in the browser and does not send or store the document body on the server. It also restricts outbound connections with Content Security Policy.
The implementation details are explained in Making “No Upload” a Structural Property, Not Just a Promise.
This does not replace your organization's security policy. If the README contains sensitive information, follow the rules that apply to that environment.
When a full editor is better than a viewer
Use a simple viewer when you only need to inspect one file.
Use VS Code or another Markdown-capable editor when you need:
- continuous editing
- project-wide search
- Git integration
- multi-file navigation
- repository-aware paths
The right tool depends on whether you are checking a README or maintaining a repository.
For the broader distinction, see Preview Markdown in Your Browser — No Install, No Upload.
FAQ
If it looks correct in a Markdown viewer, will it look identical on GitHub?
Not necessarily. GitHub uses GFM and additional site-specific processing. Use a viewer for first-pass syntax checking and GitHub for the final verification.
Why does everything after a code block render as code?
A missing closing code fence is a common cause. Check that the opening and closing backtick fences are balanced.
Can I verify relative links before publishing?
You can check the Markdown syntax, but whether the link reaches the intended repository file depends on the README location, branch, and repository structure. Verify the final path on GitHub.
Is it safe to open an unpublished README in an online viewer?
It depends on the tool. Check whether the file is uploaded to a server or processed locally. Markdown Viewer processes the file in the browser, but organizational security rules still take priority.
Summary
Use a Markdown preview to catch basic README problems before publishing.
Then use GitHub itself to verify the parts that depend on GitHub's rendering environment, especially relative links, images, task lists, and other GFM-specific behavior.
That two-step process is more reliable than expecting a generic Markdown viewer to reproduce GitHub exactly.