Guide

How to share a Markdown file as a link

Updated 30 October 2026

Pick by who should read it. A secret GitHub gist gives a link that anyone who has it can open. A private GitHub repository shows the rendered file only to people with access to it, each with a GitHub account. HackMD shares a note with signed-in users, everyone, or people you invite. ashare.net renders the .md file as a page and opens it to your company by email domain, specific emails, or anyone with a password; readers sign in with a code from their email and comment on the text.

The options side by side

Option	Who can open it	What the reader needs
Secret gist	Anyone who has the URL. Not listed in Discover or search.	The link
Public gist	Everyone, listed in Discover and search	Nothing
File in a GitHub repository	Public repository: everyone on the internet. Private: you and the people you give access.	For a private repository, a GitHub account with access
HackMD note	Read set to signed-in users or everyone: anyone who knows the URL. Or specific users you add.	A HackMD account, unless Read is set to everyone
ashare.net	Your company by email domain, up to 100 emails, or anyone with the link, with an optional password and expiry	An email inbox for a 6-digit code. No account to create.

GitHub Gist

Every gist is a Git repository, and GitHub suggests a gist with a Markdown file as a place to try its formatting. A gist is public or secret. GitHub is direct about the second kind: “Secret gists aren’t private.” A secret gist stays out of Discover and search, but anyone you send the URL to can see it, and so can anyone they forward it to. GitHub’s own advice for something you need to keep hidden is a private repository.

Good for a note you don’t mind being seen, or one shared with engineers who live on GitHub. Gist comments can be turned off or deleted.

A repository on GitHub

GitHub renders a .md file in a repository as a page; Code switches to the source. A private repository is open only to you and the people you give access, so every reader needs a GitHub account with access to that repository. That works for your engineering team. For a client or a manager outside it, it is a lot to ask for one document.

HackMD

HackMD is built for real-time Markdown collaboration. The owner sets who can read and who can edit. With Read set to signed-in users or everyone, anyone who knows the note’s URL can view it, and with everyone the note may be indexed by search engines. To limit viewers, the owner adds specific users by their registered email or username under advanced permissions. A note has up to 3 editors by default; the Prime Personal and Team plans lift that limit.

If several people should edit the text at the same time, HackMD fits better than ashare: on ashare readers comment, they don’t edit the page.

Publish Markdown on ashare.net

Create a key on ashare.net/me/api, then publish the file and say who opens it:

Terminal

$ npx ashare-cli login
$ npx ashare-cli publish spec.md --visibility company
$ npx ashare-cli share <id> marta@agency.com

Your company. --visibility company opens it to everyone who signs in with an email on your company domain.
Specific people. share <id> <email> adds up to 100 emails; each one gets a letter with the link.
A password. --visibility public --password <password> --expires 7d lets in anyone with the link and the password, for a week.

The format comes from the extension, .md or .markdown, and the title from the first heading. Headings, tables, code blocks and images render as a page. A new document is private until you share it. You can also upload the file on My documents without a terminal, or ask your agent to publish it over MCP: see Connect your agent.

Comments, versions and who read it

Readers select a line and comment. You, or the agent that wrote the file, read the open threads with npx ashare-cli comments <id>, fix the text, reply and resolve.
npx ashare-cli update <id> spec.md publishes a new version at the same link. Markdown versions are compared line by line: ?v=2&diff=1 shows what changed.
For a private or company document you see who opened it and when.
The link can embed in Notion or another site you allow, if the document is public and has no password.

Documents on ashare are kept out of search engines on purpose. For a README or a post you want people to find, a public gist or a public repository does that job better.

ashare.net: your agent publishes HTML or Markdown and you choose who opens it: your company, specific emails or a password. Readers comment, the agent fixes the document.

Connect your agent