# Preview README.md Before Publishing to GitHub - Canonical URL: https://oka-project.com/en/blog/github-readme-preview - Published: 2026-09-16 - Author: oka (https://oka-project.com/en/about) - Summary: Preview README.md before you push, then verify GitHub-specific rendering after publishing. Check headings, tables, code, relative links, images, and task lists. - Category: guide / Tags: Markdown, README, GitHub, GFM, Markdown Viewer --- 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. > [!NOTE] > **Short answer:** preview the README before publishing to catch basic Markdown problems, then verify the final result on GitHub for relative links, images, task lists, and other GitHub-specific behavior. ## 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: 1. open the README in a Markdown viewer 2. fix obvious Markdown syntax problems 3. push the file to the repository 4. check the final rendering on GitHub oka-project's [Markdown Viewer](https://oka-project.com/en/tools/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. ```md # 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: ```text 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. ````md ```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. ```md | 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](https://oka-project.com/en/blog/markdown-table-not-rendering). ### 4. Treat task lists as GitHub-specific behavior GitHub supports task lists such as: ```md - [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. ```md [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](https://oka-project.com/en/blog/browser-only-tools-csp). 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](https://oka-project.com/en/blog/markdown-preview-online). :::faq FAQ Q: 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. Q: 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. Q: 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. Q: 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. ### References - [GitHub Flavored Markdown Spec](https://github.github.com/gfm/) - [GitHub Docs: Basic writing and formatting syntax](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax) - [GitHub Docs: Working with advanced formatting](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting) - [GitHub Docs: Organizing information with tables](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/organizing-information-with-tables)