{"id":15292096,"url":"https://github.com/sgregson/dotfiles-md","last_synced_at":"2025-06-10T09:34:57.545Z","repository":{"id":62391144,"uuid":"560060462","full_name":"sgregson/dotfiles-md","owner":"sgregson","description":"Manage your dotfiles with markdown","archived":false,"fork":false,"pushed_at":"2025-05-22T01:46:21.000Z","size":57615,"stargazers_count":5,"open_issues_count":5,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-06-02T06:58:01.661Z","etag":null,"topics":["cli","dotfiles","dotfiles-manager","markdown"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sgregson.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2022-10-31T16:50:54.000Z","updated_at":"2025-06-01T09:54:33.000Z","dependencies_parsed_at":"2025-05-22T02:40:05.140Z","dependency_job_id":null,"html_url":"https://github.com/sgregson/dotfiles-md","commit_stats":{"total_commits":50,"total_committers":1,"mean_commits":50.0,"dds":0.0,"last_synced_commit":"1e97381d099260afe177fe910da7169b92b06de1"},"previous_names":["sgregson/dot-md"],"tags_count":22,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sgregson%2Fdotfiles-md","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sgregson%2Fdotfiles-md/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sgregson%2Fdotfiles-md/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sgregson%2Fdotfiles-md/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sgregson","download_url":"https://codeload.github.com/sgregson/dotfiles-md/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sgregson%2Fdotfiles-md/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259048647,"owners_count":22797772,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","dotfiles","dotfiles-manager","markdown"],"created_at":"2024-09-30T16:16:29.604Z","updated_at":"2025-06-10T09:34:57.529Z","avatar_url":"https://github.com/sgregson.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"![a logo illustrating an arrow from a glob of markdown to a glob of dotfiles](./docs/banner.png)\n\n\u003cdetails\u003e\u003csummary\u003e\u003csup\u003e\u003csub\u003ebanner image source\u003c/sub\u003e\u003c/sup\u003e\u003c/summary\u003e\n  \n  ```html title=\"logo\" disable=true\n  \u003cdiv style=\"height:3em;aspect-ratio: 6/1;font-size:3.6rem;font-weight:bold;background:linear-gradient(-0.075turn,#3f87a6,#ebf8e1,#f69d3c);color:white;text-shadow:1px 1px 3px black;display:grid;place-items:center;margin:2em 0\"\u003e\n    \u003cdiv\u003e\n      \u003ccode style=\"background-color: rgba(0,0,0,.2);padding:.2em .5em;border-radius:.25em\"\u003e*.md\u003c/code\u003e\n      →\n      \u003ccode style=\"background-color: rgba(0,0,0,.2);padding:.2em .5em;border-radius:.25em\"\u003e~/.*\u003c/code\u003e\n    \u003c/div\u003e\n  \u003c/div\u003e\n  ```\n\n\u003c/details\u003e\n\n[![GPLv3 License](https://img.shields.io/badge/License-GPL%20v3-yellow.svg)](https://opensource.org/licenses/)\n\n# dotfiles-md\n\nMaintain your system configuration as a collection of installable markdown blocks\n\n## Usage\n\n\u003e _**Requires:** node.js_. See [contributing] for instructions on installing a local copy\n\nSimply navigate to your folder of markdown and then run the interactive CLI:\n\n```sh title=\"run the program\" disabled=true\n$ npx dotfiles-md\n```\n\n![running the demo](./docs/demo_screenshot.png)\n\nOr if you have a dotfile ready-to-go, invoke it with:\n\n```sh title=\"invoke a dotfile\" disabled=true\n$ npx dotfiles-md --auto DOTFILE.md\n```\n\n[contributing]: #contributing\n\n### CLI Commands\n\n_run the `help` command to view help pages_\n\n```sh disabled=true\n$ npx dotfiles-md --help\n```\n\n## How to write Dotfiles in markdown\n\n\u003e Consult [the included demo](./demo/README.md), which may be easier to understand than the specification below.\n\n**Code block metadata**\n\nEach codeblock is created with three backticks (`) or tildes (~) and assigned a **space-delimited** collection of metadata:\n\n````md\n```\u003clang\u003e [filePath] [...options]\n[contents]\n```\n````\n\n_this should generally be compatible with other documentation systems._\n\nThe **`\u003clang\u003e` directive** is the usual markdown code block langauge format. In addition to useful syntax highlighting, this language will determine how to run imperative settings defined with `action=run` (eg. executing scripts).\n\nA **`[filePath]` option** may be provided in order to direct the output of the code block to a file. It **must not** contain an equals sign `=`.\n\nThe **`[...options]` array** is a space-delimited list of `key=value` directives defining how the CLI should act on this code block. Values must be quoted if they contain spaces (eg. `title=\"a fancy title\"`).\n\nThe **`[contents]`** of the codeblock are acted on according to the options list, particularly the \"action\" flag.\n\n**Codeblock Options and Actions**\n\n- `action` defines what dotfiles-md will do with the block contents:\n  - `=build`: build the file to `[filePath]`\n  - `=run`: run this code block according to the file syntax (js: node, sh, bash, zsh)\n  - `=symlink`: find-replace patterns (`%...`) in the codeblock and symlink the result (from `/build`) to `[filePath]`\n  - `=section`: use the contents of the code block as a section divider in the CLI\n- `disabled=\u003cstring\u003e`: prevent a block code block from being runnable. The `\u003cstring\u003e` is displayed in the UI.\n- `title=\u003cstring\u003e` a title for the code block to appear in the CLI. `\u003cstring\u003e` must be quoted if it contains spaces.\n- `when` defines the availability of this codeblock\n  - `=os.darwin`: the block will only run on MacOS platforms\n  - `=os.win32`: the block will only run on Windows platforms\n\n### Using private `.env` data\n\nIf the directory you run `dotfiles-md` from includes a `.env` file, it will be used as a source for replacements in your dotfiles. Prefix your environment variables with `%` in your dotfiles source as in:\n\n- given: an `.env` file containing `S3_BUCKET=my-fancy-bucket`\n- when: dotfiles-md encounters a dotfile containing `%S3_BUCKET`\n- then: dotfiles will replace that string with `my-fancy-bucket`\n\n## Contributing\n\nContributions are always welcome!\n\nSee `CONTRIBUTING.md` for ways to get started.\n\nPlease adhere to a reasonable `code of conduct`.\n\n### Install or Run Locally\n\n```sh action=run title=\"install and run dotfiles-md\" disable=true\n# Clone the project\ngit clone git@github.com:sgregson/dotfiles-md.git\n# Go to the project directory\ncd dotfiles-md\n# Install dependencies\nyarn\n# Run the interactive CLI\nnpx dotfiles-md --help\n```\n\n## Roadmap\n\n- [x] implement `when=\u003cconditions\u003e` (v0.3.0)\n- [x] implement `action=run` (v0.4.6) for imperative settings\n- [x] implement `action=section` for block labelling (v0.6.0)\n- [x] implement find-replace from `.env` files (v0.7.0)\n  - (idea) create sections from nearest doc heading. not sure this is actually more useful than current, but it saves some manual work\n- (idea) Update \u0026 Improve Interface UI: 2-panel layout for navigation and show a codeblock\n- (idea) Generate diff when file a exists instead of the current backup flow\n\n## FAQ\n\n#### Why markdown files?\n\nSpecifically, **literate markdown**. IMHO dotfiles (or configuration in general) should be organized in a way that makes sense to you for fast recall and organization. From there you can choose whether to manipulate your `$PATH` or direct them to known defaults (like `~/.gitconfig` vs `!/.config/git/config`).\n\nI also really liked the topic-centric approach of other dotfiles managers (like [holman/dotfiles](https://github.com/holman/dotfiles)) but found I need to give myself WAY more context on the operations than code comments since I update them so infrequently.\n\n#### Why an interactive CLI?\n\nAll my old dotfiles systems relied on either a \"bag of scripts\" folder or someone else's CLI. I loved using [kody](https://github.com/jh3y/kody) for a long time, but updating the dotfiles became difficult as my config grew stale.\n\n#### Why the repo structure?\n\n- `demo/`: A functional demo folder of dotfiles. see demo/README.md\n- `dotfiles/`: My actual, personal, dotfiles. Use for inspiration or whatever\n- `src/`: the CLI script codebase\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsgregson%2Fdotfiles-md","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsgregson%2Fdotfiles-md","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsgregson%2Fdotfiles-md/lists"}