Help / FAQ
This page explains how to use markdown.bz and what to check before you share.
About the service
What is markdown.bz?
A service that turns a Markdown file, or text you paste in, together with its images into a share page that anyone can read in a browser. Readers do not need a Markdown viewer.
Do I need an account?
No account is needed to create or view share URLs. To open a password-protected share, you need the password from the person who shared it. If you sign in with Google, the shares you created earlier in this browser move to your account, and you can list and delete them from other devices.
Sharing guides
For the basic steps, see How to share a Markdown file as a URL. If your Markdown comes with an image folder, see How to share Markdown with images as a ZIP. All guides are listed in Markdown sharing guides.
Upload
How does sharing work?
Add a Markdown file or paste your text, and add images if needed. After checking the content, set the expiry and choose whether to use a password, then create the share URL.
What files can I upload?
Markdown, JPEG, PNG, WebP, GIF and ZIP files are supported. Use a ZIP when you want to upload Markdown and images together.
Can I paste text instead of preparing a file?
Yes. Type or paste Markdown directly into the editor on the Upload page. As you write, the editor shows headings, tables, diagrams, math and more close to how they will look once published, and switching to “Preview” shows exactly how the published page will look. You can keep editing the text until you publish.
Is there a limit on how many shares I can create per day?
Yes. From the same connection (IP address), you can add up to 10 shares and 20 MB of images per day, reset at midnight Japan time. Shares created with the API count too. If you share a connection with other people, such as at work or school, their shares are counted together with yours. From the 8th share of the day, the Upload page and the page shown after publishing tell you how many more you can add today.
API
Can I create share URLs from a program or the command line?
Yes. Send Markdown text to the publishing API and you get the finished share URL back as JSON. For curl examples, options and error details, see the API docs.
Images
What happens if an image is missing?
On the share page, a missing-image placeholder appears where the image should be. The Markdown text and the other images are still shared as usual.
Are Mermaid diagrams and math supported?
```mermaid code blocks are rendered as diagrams, and math written with $...$ or $$...$$ is rendered with KaTeX. If rendering fails, the content is shown as a code block.
Are GitHub, Obsidian and HackMD callouts supported?
Yes. A blockquote whose first line is > [!NOTE], [!TIP], [!IMPORTANT], [!WARNING] or [!CAUTION] is shown as a callout with its own color and icon for each type. Obsidian’s [!abstract], [!info], [!todo], [!success], [!question], [!failure], [!danger], [!bug], [!example] and [!quote] types and their aliases are also supported, and text written after the marker, as in > [!note] Title, becomes the callout’s title. Adding -, as in [!faq]-, makes the callout collapsible and closed by default; adding + makes it collapsible and open.
Blocks fenced with ::: are shown as colored boxes. These include HackMD’s :::info, :::success, :::warning and :::danger; Zenn’s :::message (red with alert); Qiita’s :::note info, warn and alert; and Docusaurus and VitePress blocks such as :::tip Title. :::spoiler and :::details are shown as collapsible sections. A [TOC] marker, which shows where a table of contents goes, is removed from the text, because readers can already jump between headings from the Contents menu on the share page.
Are Obsidian internal links and highlights supported?
Yes. Links to a heading in the same document, such as [[#Heading|Display text]], jump to that heading on the page. Links to other notes ([[Note name]]) cannot be opened because those notes are not part of the share, so they are shown as specially marked text that is easy to tell apart from working links. Image embeds such as ![[image.png]] show the image with the same file name from the images you added, and ![[image.png|300]] sets the display width. Links to an image ([[image.png]] or [caption](images/image.png)) open the image you added in an enlarged view without leaving the page. ==text== is shown with a highlighter-style highlight.
Can I add image captions and code file names?
Yes. An image that is alone in its paragraph is centered, and a caption is shown below it, taken from an italic-only paragraph right after the image (*Figure 1: Description*) or from the image title (). Code blocks show the file name given in ```ts:app.ts (Qiita and Zenn) or ```ts title="app.ts", or otherwise the language name, in a header bar with a copy button. A line at the end of a blockquote that starts with a dash, such as — Speaker, is shown right-aligned as the source of the quote.
Can I present it as slides?
Yes. Add type: slide to the frontmatter at the top, and, as in HackMD, the document is split into slides at lines containing only --- (including ---- for vertical slides) and shown one slide at a time. Move between slides with the arrow keys or by swiping, and use full screen in supported browsers. Press “View as document” to switch to the normal document view.
Sharing and expiry
Can I choose a design for the share page?
You can choose from 7 design templates right above the pre-publish preview. Each template changes not only the colors but also the typefaces and the style of headings, tables and callouts.
- Standard: A standard look close to GitHub (default)
- Business: Headings on navy bands and tables with dark header rows, for reports and proposals
- Magazine: Justified serif text and headings set off by thin rules, for long-form reading
- Academic: Automatic section numbers on headings, first-line paragraph indents and tables with horizontal rules only
- Technical:
##marks on headings and dark code blocks, for technical documents - Notebook: A light page with few rules and softly tinted callouts, for notes and meeting minutes
- Pop: Bold headings on rounded blue bands and clearly numbered steps, for announcements and training materials
Every template adapts to your device’s dark mode and to smartphone screen widths. With the publishing API, choose one with theme (see the API docs). You can see how each one looks in the Rendering examples.
Can I choose an expiry?
You can choose no expiry, 3 days, 7 days, 30 days, 60 days or 100 days. The default is no expiry. No expiry means there is no viewing deadline, but it does not guarantee permanent storage.
What happens when a share expires?
For a share with an expiry, the text, images, downloads and link preview become unavailable once it expires. Expired shares are permanently deleted by a scheduled job, but viewing stops as soon as the expiry passes.
Can I delete shares I created?
Yes. In My shares, you can list and delete the shares created in this browser. Deleted shares can no longer be viewed, and deletion cannot be undone. The information needed to list and delete them is stored in the browser that created them, so you cannot delete them from another device or after clearing your browser data. If you sign in with Google, the shares created in this browser move to your account, and you can list and delete them from other devices by signing in with the same account. Shares moved to your account and shares created while signed in are not kept in this browser’s records, and appear in the list only while you are signed in. On a shared computer, shares that other people created in that browser would move too, so only sign in on your own device. Shares created with the API do not appear in the list, but you can delete them through the API with the delete token returned when they were created (see the API docs).
Can I share with a QR code?
After the share URL is created, you can display a QR code for it. This is useful for sharing in person, on paper or in slides.
Security
Can I set a password?
Yes. For password-protected shares, the text, images and downloads are protected. However, password protection only controls who can view the share; it is not end-to-end encryption. The operator may check the content when operationally necessary, such as when responding to a report.
Can I edit the text after publishing?
Yes. For shares listed in My shares, use “Edit” to update the text while keeping the same URL. After an update, the share page shows an “Updates & history” link, and anyone with the share URL can see the previous text and a diff of the changes. If the share contains something you want removed, delete it instead of updating it. Editing cannot extend the expiry, change the password or add images. Shares created with the API cannot be updated.
What is it not suited for?
It is not suited for sharing personal or confidential information, contracts, credentials, access keys, large files or files that need long-term storage.
Report a problem / removal request
What should I do if I find a problematic share?
Please contact us through Report a problem / removal request. If a share is suspected of rights infringement, exposing personal information, phishing, malware, dangerous links or similar problems, we review its content and suspend or delete it as needed.