Add Markdown (.md) Export Format

[diegocostares]

Current Problem

Right now brews can only be downloaded as TXT or printed as PDF from the browser.
This makes it harder to work with exported content using external Markdown editors and Git-based workflows.

Proposed Solution

Add an option to export brews as .md.

At minimum, this could export:

• the current markdown source
• brew metadata if available

It may also be useful to preserve Homebrewery-specific syntax instead of converting it.

Related Issues

• [FEATURE]: Downloadable CSS + HTML bundle #661
• Export to RTF or similar #4568

[calculuschild]

Hi! Thanks for creating this issue.

That makes it difficult to edit brews in external editors or keep them in version control while preserving the original markdown structure.

Can you clarify what is meant by this? What structure is being lost in the .txt files?

It may also be useful to preserve Homebrewery-specific syntax instead of converting it.

The .txt export already contains the raw markdown; there is no syntax being converted.

[diegocostares]

I explained that poorly in the original issue.

I didn’t mean that the .txt export loses structure. The request is more about interoperability and standard Markdown workflows.

In my case, for example, I use Obsidian to organize campaigns and notes, so exporting directly as .md fits much better with that ecosystem and tools like Git

[dbolack-ab]

A .md markdown file is just a textfile containing markdown. There is no file structure specification.

[ericscheid]

A .md markdown file is just a textfile containing markdown. There is no file structure specification.

Our download.txt files do have a file structure though.

1. codefenced blocks for 'metadata' (in YAML) and 'css' (in css)
2. the brew.text itself, following (1)
3. given that codefenced blocks are also markdown, the entire download.txt file is also fully markdown

@diegocostares have you looked at a HB-download.txt file ??

[diegocostares]

Yes, I did look at the current download.txt format, and I understand that it already is valid markdown structurally. My suggestion was mostly about convenience and integration with markdown-oriented tooling. Since I already manage campaigns and notes in Obsidian, exporting directly as .md would fit more naturally into that workflow without needing to rename files manually every time. So this is less about missing functionality in the current export and more about ergonomics and interoperability with the broader markdown ecosystem.

[ericscheid]

IIRC, the choice of file extension at the time was based on the low tech knowledge of the intended audience (i.e. our authors, who likely don't have an OS mapping of .md → text editor, let alone one that knows about MD).

The whole download.txt is markdown, but important to note that it is the brew markdown (what you see in the editor) preceded by two codefenced blocks. One for metadata, one for css.

So ...

Add an option to export brews as .md. At minimum, this could export:

• the current markdown source
• brew metadata if available

The .txt download already does exactly that.

Out of curiosity, how does Obsidian and Notion handle document metadata (i.e. on export)

[diegocostares]

In Obsidian, metadata is usually handled through YAML frontmatter at the beginning of the .md file, although many plugins and workflows also work directly with “normal” markdown files.

For example:

---
title: The Lost Mine
campaign: Phandelver
session: 12
tags:
  - dnd
  - goblins
  - bossfight
---

# Session Notes

The party entered the ruined temple...

And when you end up with lots of interconnected files, it starts forming a really beautiful graph view:

[ericscheid]

Fair.

Where obsidian uses --- to separate front matter from document contents, home brewery uses code fences with info strings ( i.e. \```metadata and \```css)

Also just realised .. our metadata yaml block might not align perfectly with Obsidians metadata yaml block. Both 'title' and 'tags' appear to map, but nothing else.

```metadata
title: Coins of Vaalbara
description: ''
tags:
  - type:Campaign
  - Vaalbara
systems: []
renderer: V3
theme: 5ePHB
```

[5e-Cleric]

We could add an export specifically for obsidian, since it is very popular and it would require little changes.

It could consist of:

• Swapping ``` for ---
• removing renderer, theme, description, anything that obsidian doesn't use

[ericscheid]

and the css block? wrap it with <style/> ?

[5e-Cleric]

and the css block? wrap it with <style/> ?

I'd nuke it, does obsidian even allow css?

[dbolack-ab]

Seems like a Homebrewery importer for Obsidian is a better target.

[diegocostares]

I still think it could be interesting to eventually move the metadata block closer to standard YAML frontmatter (---), even if an Obsidian importer/plugin also exists.

Not specifically because of Obsidian, but because YAML frontmatter is already a very common pattern across the Markdown ecosystem. Tools like Jekyll, Hugo, Obsidian, Astro, VuePress, and many documentation/static-site workflows already use that format.

And regarding CSS: Obsidian does support custom styling, although it is usually handled more through themes, CSS snippets, and plugins rather than embedded per-document CSS blocks.

[5e-Cleric]

Time for being brutally honest. Its not a very hard thing to do, but its definitely not a priority for us. We've got 2 votes for closing this issue so we can focus on other features, and no votes for not closing it so far.