markdown.bz

Markdown sharing guides / Share a README outside GitHub

How to share a README with people outside GitHub

When you share a README through GitHub, viewers may need access to a private repository or a GitHub account. With markdown.bz, you can turn the README under review into a standalone web page and give it to anyone who has the URL.

1. When a share URL is the right choice

SituationBest approach
Developers reviewing a public repository togetherThe README URL on GitHub
Clients or users outside GitHub reviewing itA markdown.bz share URL
Reviewing only the README of a private repositoryCreate a README for sharing with confidential information removed
Freezing the content as of the reviewA share URL with an expiry

Share pages do not sync with the repository. Use them as a snapshot at the time of review, and keep managing the latest version in Git.

2. Prepare a README for sharing

  1. Open the README on the target branch and check its headings, steps and links.
  2. Remove internal URLs, private repository URLs, personal information and access tokens.
  3. If there are local images, put the README and the image folder together in the same parent folder.
  4. Order the setup steps so that a first-time reader can run them from top to bottom.

If it includes local images, follow How to share Markdown with images as a ZIP to create a ZIP that keeps the relative paths.

3. Create a review URL

  1. Add the README or ZIP on the Upload page.
  2. In the preview, check the table of contents, tables, code, images and links.
  3. Choose 3 or 7 days for a short review, or no expiry if the end date is undecided.
  4. Set a password only if you need to restrict who can view it.
  5. Click Publish and copy the resulting URL.

4. Send it with what to check

Including what to review and the deadline, not just the URL, cuts down on back-and-forth.

Could you please review the README?

Review URL: https://markdown.bz/d/SHARE_ID
Review by: August 10
Please check:
- Whether the steps can be completed with the initial setup alone
- Whether anything is missing from the command examples
- Whether the terms make sense to a first-time reader

Share pages have no comment feature, so tell reviewers separately where to send feedback, such as a GitHub issue, email or chat.

5. When you update the README

Once you have addressed the review comments, you can update the text from "My shares" while keeping the same URL. The share page gets an "Updates & history" link, so reviewers can check just the changes since last time. When you ask for another review, include the commit or update date in your message so they know which version to look at.

6. Pre-publish checks

  • Do not include .env values, API keys, cookies or internal host names
  • Check whether the very existence of the private repository needs to be kept secret
  • Choose the content on the assumption that anyone with the URL can view it
  • Do not use password protection as a substitute for confidential storage or end-to-end encryption
  • Keep originals that need long-term retention in the Git repository

Create a share URL for your README

Last reviewed: / Reviewed by the markdown.bz team