# @sgregson/dot-md

> Manage your dotfiles with markdown

Latest version **0.1.1** (published 2022-11-01) · GPL-3.0-or-later license · 0 weekly downloads

## Install

```sh
npm install @sgregson/dot-md
pnpm add @sgregson/dot-md
yarn add @sgregson/dot-md
bun add @sgregson/dot-md
```

Provides the command `dot-md`.

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: abandoned.

## Facts

| | |
|---|---|
| Version | 0.1.1 |
| Published | 2022-11-01 |
| First published | 2022-11-01 |
| Weekly downloads | 0 |
| License | GPL-3.0-or-later |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >15 |
| Dependencies | 11 |
| Unpacked size | 19.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 7 |
| Author | Spencer Gregson |
| Maintainers | sgregson |
| Keywords | dotfiles, markdown, cli |

## Links

- npm: https://www.npmjs.com/package/@sgregson/dot-md
- Repository: https://github.com/sgregson/dot-md
- Homepage: https://github.com/sgregson/dot-md#readme
- Issues: https://github.com/sgregson/dot-md/issues
- npm.io page: https://npm.io/package/@sgregson/dot-md

## Dependencies (11)

- [glob](https://npm.io/package/glob.md) ^8.0.3
- [dotenv](https://npm.io/package/dotenv.md) ^16.0.3
- [vorpal](https://npm.io/package/vorpal.md) ^1.12.0
- [unified](https://npm.io/package/unified.md) ^10.1.2
- [fs-extra](https://npm.io/package/fs-extra.md) ^10.1.0
- [inquirer](https://npm.io/package/inquirer.md) ^9.1.4
- [remark-gfm](https://npm.io/package/remark-gfm.md) ^3.0.1
- [remark-parse](https://npm.io/package/remark-parse.md) ^10.0.1
- [unist-util-visit](https://npm.io/package/unist-util-visit.md) ^4.1.1
- [remark-frontmatter](https://npm.io/package/remark-frontmatter.md) ^4.0.1
- [escape-string-regexp](https://npm.io/package/escape-string-regexp.md) ^5.0.0

## Alternatives

- [@salesforce/cli](https://npm.io/package/@salesforce/cli.md) — 389.7K weekly downloads
- [@mintlify/cli](https://npm.io/package/@mintlify/cli.md) — 208.9K weekly downloads
- [@grafana/e2e-selectors](https://npm.io/package/@grafana/e2e-selectors.md) — 128.7K weekly downloads
- [mintlify](https://npm.io/package/mintlify.md) — 112.0K weekly downloads
- [@intlayer/cli](https://npm.io/package/@intlayer/cli.md) — 22.8K weekly downloads

## Recent versions

- 0.1.1 (latest) — 2022-11-01
- 0.1.0 — 2022-11-01

## README

# Literate Dotfiles

Every code block in a folder of Markdown can be compiled, symlinked, or run.

## Usage

> Requires NodeJS to be installed

1. navigate to your folder of markdown files
1. Run `npx dot-md`

## Installation

It's recommended to run the command line tool via `npx` rather than installing a local copy.

> To use offline, `npm i -g dot-md` and run with `npx dot-md --no`. NOTE: this will not auto-update

Read CONTRIBUTING.md for contributing code changes or installing locally.

## Why?

**literate markdown** IMO dotfiles should be organized in a way that makes sense to you, for fast recall and organization – but you ultimately need to either place them in a specific location or manipulate your `$PATH`.

I really liked the topic-centric approach of [other markdown systems] but found I need WAY more context than code comments since I update them so infrequently.

**CLI** All my old dotfiles systems relied on either a "bag of scripts" folder or someone else's CLI. I loved `kody` for a long time, but updating the actual dotfiles became difficult as my config grew stale.

## How this repo is organized

- `demo/`: A functional demo folder of dotfiles. see demo/README.md
- `dotfiles/`: My actual, personal, dotfiles. Use for inspiration or whatever
- `src/`: the CLI script codebase

## Code blocks as metadata

Each codeblock is created with three backticks (`) or tildes (~) and is provided extra data in a **space-delimited** collection:

    ```<lang> [filePath] [...options]
    ```

The `<lang>` is the usual markdown code block langauge format. It is used to specify the syntax highlighting of the code snippet but may in the future be used to direct the `action=run` directive.

A `[filePath]` may be provided in order to direct the output of the code block. It **must not** contain an equals sign `=`.

The `[...options]` array is a space-delimited list of `key=value` directives defining how the CLI should act on this code block:

- `disabled=true` disable this code block from being run (helpful for migrations)
- `title=<string>` a title for the code block to appear in the CLI. `<string>` **msut not** contain spaces.
- `action` defines what to do with the content
  - `=build`: build the file to `[filePath]`, replacing content as appropriate
  - `=symlink`: find-replace patterns (`%...`) in the codeblock and symlink the result (from `/build`) to `[filePath]`
  - `=include`: build the block into a place included in your shell (`/build/includes/`) TODO: not implemented
  - `=run`: run this code block according to the file syntax (js: node, sh: bash, zsh) TODO: not implemented yet
- `when` defines the availability of this codeblock
  - `=npm`: when npm is available (after nvm install)
  - `=os.platform()==='darwin'`: only on macos

[literate markdown]: http://www.literateprogramming.com/knuthweb.pdf

f

---
_Source: https://npm.io/package/@sgregson/dot-md · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._