Bike Markdown Format

Bike Markdown (.bikemd) is Bike's text-based file format. It's a subset of standard markdown — open a .bikemd file in any markdown viewer and it will render reasonably well.

Markdown Subset

Bike Markdown uses standard markdown unordered lists to encode outline hierarchy. Each row is a list item (- ), and indentation creates nesting:

- Parent
	- Child
		- Grandchild
	- Another child

This is valid markdown — any markdown renderer will display it as a nested list.

Row Types

Within that list structure, Bike uses standard markdown syntax to represent different row types:

Type	Syntax	Example
Body	-	- Regular text
Heading	- #	- # Section title
Blockquote	- >	- > Quoted text
Task	- [ ]	- [ ] Incomplete task
Task (done)	- [x]	- [x] Completed task
Ordered list	1.	1. First item
Unordered list	+	+ Bullet item
Code block	- `...`	- `code content`
Horizontal rule	- ---	- ---

Most of these — headings, blockquotes, task checkboxes, ordered lists — are standard markdown or widely supported extensions (like GFM task lists).

Text Formatting

Inline formatting uses standard markdown syntax:

Format	Syntax
Bold	**text**
Italic	*text*
Strikethrough	~~text~~
Code	`text`
Link	[text](url)

Pandoc Attributes

Standard markdown has no way to attach metadata to rows or text spans. Bike rows and text can carry attributes — persistent IDs, classes, timestamps, custom data — that need to be preserved in the file.

Bike Markdown uses Pandoc's attribute syntax to fill this gap. Attributes are written in curly braces and support IDs, classes, and key-value pairs:

{#identifier .class key="value"}

Pandoc attributes are only written when a row or span actually uses features that require them. Plain rows with standard formatting won't have any attribute blocks in the output.

Row attributes appear at the end of a row:

- A note {type=note}
- Styled row {.highlight}

Row IDs are encoded in the markdown only when they are referenced by a link within the document, or when the ID appears to have been set explicitly (i.e. it doesn't look auto-generated). Auto-generated IDs are omitted to keep the file clean:

- # Section {#intro}
- See the [intro section](#intro)

Inline attributes use Pandoc's bracketed span syntax [text]{attrs} for formatting that has no standard markdown equivalent. For example, highlighted text:

- This has [highlighted text]{highlight} in it

Or custom attributes on a span of text:

- Price is [lo]{pizza}

Bike uses standard markdown syntax when it can (**bold**, *italic*, etc.) and falls back to [text]{attrs} only when there's no markdown equivalent.

Frontmatter

Files can optionally begin with a JSON metadata block between --- delimiters:

---
{"bikemd":true,"root-id":"c43J5daN"}
---

- First row

The frontmatter preserves document metadata like the root ID and spell-checker ignore words. Bike manages this automatically — you don't need to edit it by hand.

Escaping

Characters that would normally be interpreted as row type prefixes are escaped with a backslash:

- \# This is not a heading
- \> This is not a blockquote
- \+ This is not a list item

Standard markdown escaping also applies for inline formatting characters like *, `, [, ], etc.

Example

Here's a complete example showing several features together:

---
{"bikemd":true,"root-id":"root123"}
---

- # Project Notes {#notes}
	- This has **bold** and *italic* text
	- A row with [highlighted words]{highlight}
	- > An important quote
	- [ ] Review the [documentation](https://example.com)
	- [x] Write initial draft {done}
	1. First step
	2. Second step
	+ A bullet point
	- `console.log("hello")`
- ---
- # Another Section
	- Regular body text {created="2024-02-26"}