README preview prevents avoidable surprises after a commit
README.md is often the first instruction page a project visitor sees. It should quickly explain what the project does, how to install it, how to run a useful example, and where to get help. One small source error, such as an unclosed code fence or a broken relative image, can obstruct those tasks.
Open the file in the online Markdown viewer before committing to compare source and output side by side. This catches common Markdown and GFM layout problems. Repository paths, badge services, and GitHub-specific rendering still need a final check on the destination platform.
Give readers a structure they can scan
No single template fits every repository, but a developer tool README often works well in this order:
- Project name and one precise description.
- Optional status badges and a real product screenshot.
- Prerequisites and the shortest correct installation command.
- A minimal example that a reader can copy and run.
- Configuration, common workflows, and limitations.
- Testing, contribution, license, and support information.
Use heading levels as a continuous hierarchy. A README normally has one H1 followed by H2 and H3 sections. Do not skip from H2 to H4 just to make text look smaller. Opening the preview's table of contents makes hierarchy gaps and overly long headings easier to spot.
The pre-commit GFM checklist
Tables
Check the header delimiter row, the number of pipes, and the result at a narrow width. If every cell contains a paragraph, a six-column table is probably less readable than a set of short lists. Line breaks and complex HTML inside table cells can also vary across platforms.
Task lists
Use - [ ] and - [x] with the expected spacing. Task lists work for roadmaps and completion states. Avoid presenting a required installation step as a checkbox that looks interactive but cannot actually be changed by the reader.
Code blocks
Close every code fence and add the correct language identifier. Omit shell prompt characters from commands so that users can copy them directly. Separate Bash and PowerShell instructions instead of combining incompatible commands in one block.
npm install
npm run devLinks and images
A relative link resolves from the README's repository location. Paths such as ./docs/setup.md or ../assets/demo.png may not render in a generic local preview that lacks the repository base URL, yet work on GitHub. A link using an absolute path from your own computer will fail after commit.
Check each of these details:
- File-name capitalization exactly matches the repository.
- Images use repository-relative paths or stable HTTPS addresses.
- Heading anchors are updated after a heading is renamed.
- External links do not lead to a page visible only in your signed-in session.
- Images include brief, specific alternative text.
Mermaid, math, and embedded HTML are platform-dependent
GitHub supports GFM and particular Mermaid code blocks, but npm, PyPI, internal documentation systems, and other Git hosts can support a different set. KaTeX formulas, GitHub Alerts, footnotes, and emoji all need validation against the actual publishing destination.
Raw HTML differs even more. Platforms and previewers commonly remove scripts, event attributes, and dangerous elements for security. This site's reader does not parse embedded HTML by default, which prevents an untrusted README from executing it during preview. As a result, a document that relies on <details> or complex HTML tables will not look exactly like GitHub here.
See the Markdown online preview compatibility guide for a fuller explanation of these boundaries.
Test the README as a real reader task
A clean preview does not mean the instructions are complete. Approach the document as someone who has never seen the project:
- From the first screen, can you identify the purpose and intended user?
- From an empty directory, do the installation steps state every prerequisite?
- Does the smallest copyable example produce the documented result?
- Do configuration options state defaults, requirements, and sensitive-value handling?
- When something fails, can you find troubleshooting guidance, an issue template, or a support route?
A renderer cannot answer these questions for you, but previewing makes the boundaries between explanation, commands, and output easier to inspect.
Review desktop and mobile widths
README visitors do not all use desktop screens. Narrow the window and look for:
- long project names, URLs, or commands that cannot wrap;
- a table causing the entire page to scroll horizontally;
- screenshots with inappropriate fixed dimensions;
- too many badges pushing the useful introduction down;
- a table of contents or long list that is difficult to scan.
Do not align content with runs of spaces for one desktop width. Markdown's structured approach should allow the page to reflow across devices.
Privacy and external resources
This viewer processes a selected local README and pasted text in the browser. Explicitly loading a raw URL requests the corresponding remote host. External images in the document can also produce third-party requests on the final platform, so examples should not contain tracking URLs tied to a user.
A generated share link stores its document after the URL fragment and does not send that fragment to this site's server. The full URL may still remain in history or be forwarded by its recipient. Do not share private repository details, keys, or internal hostnames this way.
Recommended review order
- Verify the content and commands locally.
- Use the online reader to check general GFM layout, headings, code fences, and narrow-screen behavior.
- Run the repository's Markdown lint, link checker, or documentation build if available.
- Push a branch and review relative resources and extensions in GitHub's final renderer.
- Ask someone unfamiliar with the project to complete the minimum task and record where the instructions fail them.
If you do not yet have a suitable way to inspect the file, read how to open .md files on desktop and mobile. When the file is ready, preview README.md online.