shotanue / markdot

Markdown driven dotfiles.

Markdown Dotfile

Markdot is a tool for dotfile management with markdown.

Installation

brew install shotanue/tap/markdot

How to use

markdot dotfile.md

• dotfile.md

# sample

Markdot evaluates codeblocks in sequence.

This codeblock is evaluated as shell script.
```sh
echo "hello world"
```

## install brew

```bash
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
```

## install tools

For a brewfile code block, Markdot runs `brew bundle` and passes this content to the command.
In this sample, `git` and `mise` is installed by homebrew.
```brewfile
brew "git"
brew "mise"
```

## install editors

You can split brewfile definitions.
```brewfile
brew "helix"
brew "vim"
brew "emacs"
```

## configs

Write mise config to given path, specifying the path with `::to` tag.
```toml ::to=~/.config/mise/settings.toml
experimental = true  
```

Codeblock execution

Codeblock with some of language tags will be executed.

Supported languages are below.

```sh
echo foo
```

```bash
echo foo
```

```zsh
echo foo
```

```fish
echo foo
```

```nushell
echo foo
```

```nu
echo foo
```

brewfile

You can install brew packages with Brewfile syntax.

homebrew-bundle

Installing brew, cask and mas packages.
```brewfile
brew "git"

cask "figma"

mas 'Tailscale', id: 1475387142 
```

You can give argument `brew bundle` command.

```brewfile ::args="--verbose --no-lock"
brew "git"
```

Tags

You can write codeblocks with single tag.

Every tag requires :: prefix.

::ignore

This codeblock is ignored at runtime, which is useful in some usecases like notes.

## How to setup

```bash ::ignore
make install
```

::to

Markdot copies the codeblock content to given path, without codeblock execution.

When you want write some config files, this tag is useful.

Copying this toml to the path.
```toml ::to=~/.config/foo/config.toml
experimental = true
```

In this example, Markdot simply copies this script to the given path, without executing the bash script.

Skip running, and copying this script to the path.
```bash ::to=~/.local/bin/foo
echo foo
```

permission (optional)

You can set permission to the file with ::permission tag.

```bash ::to=~/.local/bin/foo ::permission=755
echo foo
```

::args

You can give arguments to command codeblock runs.

Giving options `--verbose --no-lock` to `brew bundle`.
```brewfile ::args="--verbose --no-lock"
brew "git"
```

fragment

You can filter which code blocks to run. Markdot accepts fragments similar to URLs.

markdot dotfile.md#bar

• dotfile.md

Fragment: `bar` is applied to this outline:
- # sample
  - ## foo
    - ### bar <-- evaluated
      - #### buzz <-- evaluated
  - ## hoge

# sample

## foo

```bash
echo "ignored"
```

### bar

```bash
echo "evaluated: bar"
```
#### buzz

```bash
echo "evaluated: buzz"
```

## hoge

```bash
echo "ignored"
```

hyperlink(symlink)

You can create symlink with hyperlink syntax.

This example creates symlink to `~/.config/nushell` from `~/Library/Application Support/nushell`.

[~/Library/Application\ Support/nushell](~/.config/nushell)

preprocessor

Markdot includes mustache.js as text preprocessor, so you can rewrite dotfile just before evaluation. This is useful when setting os specific configurations.

Given parameters are below.

• arch
• platform
• hostname
• username
• ignore

Example: Install only MacOS and username is foo.

{{#platform.darwin}}
{{#username.foo}}
### Darwin
```brewfile
cask "figma"

mas 'Tailscale', id: 1475387142 
mas 'Kindle', id: 302584613
```
{{/username.foo}}
{{/platform.darwin}}

Example: Ignore

{{#ignore}}
```bash
echo "this codeblock is ignored."
```
{{/ignore}}

```bash
echo "this codeblock is evaluated."
```

Config

You can write config to frontmatter. YAML and TOML are supported.

+++
[env.append]
# Append value to PATH. If PATH is not exist, just set the value.
PATH=":/opt/homebrew/bin:/usr/local/bin:/home/linuxbrew/.linuxbrew/bin"
[env.override]
# Override value. Override is prior to env.append.
DOTFILES_HOME="$HOME/ghq/github.com/shotanue/dotfiles"
+++

Help

markdot --help

Development

requirements

• bun.sh

markdot's Issues

Dependency Dashboard

This issue lists Renovate updates and detected dependencies. Read the Dependency Dashboard docs to learn more.

This repository currently has no open or pending branches.

Detected dependencies

github-actions

.github/workflows/code-quality.yml

• actions/checkout v4
• oven-sh/setup-bun v1
• ubuntu 22.04

.github/workflows/release.yml

• actions/checkout v4
• oven-sh/setup-bun v1
• svenstaro/upload-release-action 2.9.0

npm

package.json

• arg 5.0.2
• chalk-template 1.1.0
• immer 10.1.1
• mustache 4.2.0
• remark-breaks 4.0.0
• remark-frontmatter 5.0.0
• remark-gfm 4.0.0
• remark-parse 11.0.0
• smol-toml 1.2.0
• unified 11.0.4
• unist-util-flat-filter 2.0.0
• unist-util-visit 5.0.0
• xstate 5.13.0
• yaml 2.4.2
• zod 3.23.8
• @biomejs/biome 1.7.3
• @types/mdast 4.0.4
• @types/mustache 4.2.5
• bun-types 1.1.8
• typescript ^5.0.0

---

• Check this box to trigger a request for Renovate to run again on this repository

Action Required: Fix Renovate Configuration

There is an error with this repository's Renovate configuration that needs to be fixed. As a precaution, Renovate will stop PRs until it is resolved.

Location: renovate.json
Error type: Invalid JSON (parsing failed)
Message: Syntax error: expecting end of expression or separator near "] "labe