markdown

Exports the current palette as a portable Markdown theme file with YAML frontmatter. This is not an app-specific output plugin — it's tinct's serialization format. The generated file is the canonical way to share a tinct theme with someone else, archive a palette you generated from a wallpaper, or re-import the same palette later via tinct generate -i markdown.

Installation

Built into tinct — nothing to install separately. tinct generate -o markdown works out of the box.

Quick start

tinct generate -i image -p ~/Pictures/wallpaper.jpg -o markdown --markdown.name "sunset"

--markdown.name is required — it's used both for the filename and the name: field in the frontmatter.

Generated files

File	Path	Role
<slug>.md	~/.config/tinct/themes/<slug>.md	Markdown file with YAML frontmatter. Contains the palette name, generator version, generation timestamp, optional wallpaper (embedded as base64 or referenced by path), every colour role with its hex value and weight, and any position* ambient region colours. The filename slug is derived from --markdown.name (lowercased, non-alphanumerics replaced with hyphens).

The file is self-describing: each colour appears in a Markdown table for human readability and in the YAML frontmatter for machine re-import.

Generated format

The markdown file contains structured metadata that can be parsed by tinct:

# sunset-forest

A theme generated by tinct.

## Metadata

- **Version:** 1.0
- **Generator:** tinct v0.1.0
- **Generated:** 2024-01-15T10:30:00Z

## Colors

| Role | Hex | Weight |
|------|-----|--------|
| background | #1e1e2e | 0.15 |
| foreground | #cdd6f4 | 0.10 |
| accent1 | #89b4fa | 0.08 |
| accent2 | #f5c2e7 | 0.07 |
| danger | #f38ba8 | 0.05 |
| success | #a6e3a1 | 0.05 |
| warning | #f9e2af | 0.05 |
| info | #94e2d5 | 0.05 |

## Ambience

| Region | Hex | Weight |
|--------|-----|--------|
| top_left | #2d1f3d | 0.12 |
| top_right | #1f2d3d | 0.10 |

## Wallpaper

[EMBEDDED:image/jpeg]
/9j/4AAQSkZJRgABAQAAAQABAAD...

Integration

There's no app to integrate with. Two consumers:

• Share: send the .md file to someone else (or check it into git). They can re-import it as a theme:

  tinct generate -i markdown -p shared-theme.md -o ghostty,waybar,dunst

• Re-import: round-trip the same palette through tinct without re-running the original input plugin (useful when the input was a slow AI palette generation, a paid API call, or an image you no longer have):

  tinct generate -i markdown -p ~/.config/tinct/themes/sunset.md -o <whatever>

If the markdown was generated with --markdown.no-embed then the file references the wallpaper by absolute path. If the wallpaper was embedded (the default), the data: field holds the base64-encoded image bytes and the file is fully self-contained.

Reload behaviour

Automatic

None — there is no app to reload. The plugin only writes the file.

Manual fallback

No manual action is required. To "use" the theme, run tinct generate -i markdown -p <file>.md -o <plugins> against the apps you want to update.

Uninstall / revert

1. Remove the config line: none added. The markdown plugin doesn't touch any app config.

2. Delete the generated file:

   rm ~/.config/tinct/themes/<slug>.md

3. Reload to drop the theme: nothing to reload — the file isn't consumed by any running process.

4. External state: this plugin only writes to ~/.config/tinct/themes/. No further cleanup is required.

Flags

Flag	Default	Description
--markdown.name	(required)	Theme name; used as name: in frontmatter and as the basis for the filename slug
--markdown.dir	~/.config/tinct/themes	Override the output directory
--markdown.no-embed	false	Reference the wallpaper by absolute path instead of embedding it as base64
--markdown.include-thumbnail	false	Render a downscaled JPEG thumbnail in the Markdown body (in addition to the embedded wallpaper)

Colour role mapping

Unlike app plugins, markdown does not map roles to app keys — it serialises the entire palette. Each colour from palette.Colours is written verbatim under its tinct role name. Ambient region colours (those whose role starts with position, e.g. positionTopLeft) are placed under a separate ambience: list with the region rewritten as snake_case (top_left).

Example excerpt:

colors:
  - hex: "#1e1e2e"
    weight: 100
    role: background
  - hex: "#cdd6f4"
    weight: 100
    role: foreground
  # ... every other role from the palette
ambience:
  - hex: "#7287fd"
    weight: 12
    region: top_left

Customising the template

This plugin builds its output programmatically (no text/template is involved — it serialises a themeformat.Theme struct via themeformat.Generate). There is no template to dump.

If you need a different output format, write a different output plugin, or post-process the YAML frontmatter with yq.

Troubleshooting

Error: --markdown.name is required

Pass --markdown.name "something". It's the only required flag.

Wallpaper file is huge

Embedded wallpapers inflate the markdown ~1.33× (base64 overhead). For wallpapers >5 MB consider --markdown.no-embed and keep the image alongside the markdown file, or downscale the wallpaper before generating.

failed to read wallpaper

You either passed --markdown.no-embed against an unreadable wallpaper path, or the input plugin's WallpaperPath points at a file that no longer exists. Either drop the wallpaper input or --markdown.no-embed it (a missing-file path is preserved verbatim, useful for "this palette came from this image, which lives over there").

Re-import doesn't match the original generation

tinct generate -i markdown is faithful to what's in the frontmatter, so any role missing from the file will be missing on re-import. If the original generation used a newer tinct that emits roles your importing tinct doesn't know about, those unknown roles are skipped. Re-generate with the newer tinct on both ends.

Related plugins

• All other output plugins — markdown serialises the same palette they consume; pair it with any of them on a single tinct generate line to ship the theme files and a portable copy of the palette in one go.