markdown.style

HomeStyle a README as a document

Use cases

Turn a README into a document someone can just read

A README is written for a code host. Paste it here and the commands, options table and config block keep their formatting for a reader who has no repository open.

Open this example in the editorStart with your own

Getting your README in

Paste the file's raw text into the source pane, or use Open, which accepts only .md and .markdown files. Dropping a .md file onto the source pane does the same thing. None of these upload anything: rendering, theming and exporting all run in the browser, so the file never leaves the machine it came from.

What survives leaving GitHub

Headings, paragraphs, links, blockquotes and nested lists render the same way. Task lists still show as checkboxes. GitHub-flavoured tables render, including an options table, keeping their columns. Fenced code blocks keep their language and get syntax colour. Footnotes and raw HTML inside the file render too, with any style or script tag removed.

Two GitHub-only features do not carry over. A GitHub alert, a blockquote whose first line names NOTE, TIP, WARNING or a similar label in brackets, renders as an ordinary quoted line. An emoji shortcode such as :rocket: renders as that literal text rather than an emoji. Neither is part of this renderer.

Highlighting for the languages a README actually uses

Code fences get colour for twelve languages: bash, css, go, javascript, json, markdown, python, rust, sql, typescript, xml and yaml. That covers the install command, the usage examples and a configuration block in one document, provided each fence names its language. Name each fence, for example ```bash for a shell command or ```yaml for a config file.

Worked example

A README for a command-line tool, with install and usage commands, an options table and a configuration block.

# shotname

Renames photo files using the capture date read from EXIF metadata.

## Install

```bash
cargo install shotname
```

## Usage

```bash
shotname ~/Pictures/Trip
shotname --recurse --tz UTC ~/Pictures/Archive
```

The first line renames files in one folder. The second walks subfolders and
reads timestamps as UTC instead of the local zone.

## Options

| Flag | Argument | Default | Description |
|---|---|---|---|
| `--format` | pattern | `YYYY-MM-DD_NNN` | Output filename pattern |
| `--tz` | zone | `local` | Timezone used to read EXIF timestamps |
| `--recurse` | none | off | Include files in subfolders |
| `--on-conflict` | mode | `skip` | `skip`, `suffix` or `overwrite` when two files resolve to the same name |

## Configuration

A `.shotname.yaml` file in the target folder sets defaults so flags are
optional on every run:

```yaml
format: "YYYY-MM-DD_NNN"
tz: local
recurse: false
on_conflict: skip
```

## Why

Camera filenames reset per card, so two shoots can both produce `IMG_0001.jpg`
in the same album. shotname reads the EXIF `DateTimeOriginal` field and falls
back to the file's modified time when a photo carries no metadata. In a test
folder of 320 files it renamed 312 and skipped 8 that had no timestamp and no
fallback the tool could trust.

Licence: MIT.

Rendered in the Repo theme. Open it in the editor to change the theme or the text.

Why the Repo theme

Repo uses the system font stack with JetBrains Mono for code, blue links, rules under the two top heading levels and zebra-striped tables. That is the look of a README rendered on a code host. A reader who is used to seeing READMEs on GitHub sees the same shape here.

Two alternatives suit the same content differently. Mono sets everything in IBM Plex Mono on a wider column, which keeps long install commands and flag lines from wrapping. Carbon is a dark theme for reading code-heavy notes on a screen, and still prints as dark text on white if the page ends up on paper.

Sharing it outside the repository

"Download .html" writes one file with the theme's CSS embedded, so the tables, code blocks and options table keep their formatting. Anyone who opens it in a browser sees the same page, repository or not. Fonts still load from Google Fonts when the file is opened, so an offline reader sees a fallback font instead.

"Print or save as PDF" hands the job to the browser's own print dialog, and "Save as PDF" is there among the printer choices. That is the quickest way to hand a client or a non-developer teammate a single page instead of a link to a raw file. A dark theme such as Carbon still prints as dark text on a white page, so the printed copy stays readable without the ground colour.

"Copy styled HTML" is a third option, for pasting the rendered README straight into an email or a CMS editor without exporting a file first. The styling comes across; bullet and numbered list markers may not survive the paste.

Questions

Do GitHub alerts and emoji shortcodes still work?

No. A GitHub alert, the coloured NOTE or WARNING box at the top of a blockquote, renders as a plain quoted line here. A shortcode such as ":tada:" renders as the literal text, since both are GitHub-specific and outside this renderer.

Which fence names get syntax colour?

bash, css, go, javascript, json, markdown, python, rust, sql, typescript, xml and yaml. Name the fence with the exact language, for example bash for a shell command.

Does the person I send the .html file to need anything installed?

A browser. The file carries the theme's styling and pulls its fonts from Google Fonts, so no repository, no markdown.style visit and no editor is required to read it.

Will a dark theme print as a dark page?

No. Dark themes such as Carbon print as dark text on a white page, so a handed-out copy stays readable on paper.