{"id":37224259,"url":"https://github.com/kevineaton/d2tosite","last_synced_at":"2026-01-15T01:40:46.245Z","repository":{"id":171830994,"uuid":"581438183","full_name":"kevineaton/d2tosite","owner":"kevineaton","description":"A simple tool to convert a filesystem of markdown and D2 files to a site. A \"scratch your own itch\" project","archived":false,"fork":false,"pushed_at":"2023-10-02T15:49:05.000Z","size":7597,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-06-21T19:26:57.222Z","etag":null,"topics":["d2","hacktoberfest"],"latest_commit_sha":null,"homepage":"","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kevineaton.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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}},"created_at":"2022-12-23T07:25:51.000Z","updated_at":"2023-09-27T15:53:02.000Z","dependencies_parsed_at":"2023-10-02T20:05:13.306Z","dependency_job_id":null,"html_url":"https://github.com/kevineaton/d2tosite","commit_stats":null,"previous_names":["kevineaton/d2tosite"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/kevineaton/d2tosite","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kevineaton%2Fd2tosite","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kevineaton%2Fd2tosite/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kevineaton%2Fd2tosite/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kevineaton%2Fd2tosite/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kevineaton","download_url":"https://codeload.github.com/kevineaton/d2tosite/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kevineaton%2Fd2tosite/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28441031,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-15T00:55:22.719Z","status":"ssl_error","status_checked_at":"2026-01-15T00:55:20.945Z","response_time":107,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["d2","hacktoberfest"],"created_at":"2026-01-15T01:40:45.536Z","updated_at":"2026-01-15T01:40:46.228Z","avatar_url":"https://github.com/kevineaton.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"# D2 to Site\n\nA simple tool built to scan a file system, compile any D2 files there, and combine them with the Markdown files to generate a simple static website.\n\n## Assumptions\n\nThis project started as a need to host a bunch of D2 architecture and user flow images. Placing them in PDFs was painful, as they would span multiple pages uncomfortably. Placing them on Confluence and other wiki-style tools was better, but keeping them up to date was a challenge. Instead, the desire would be to have a repo that, every time a commit was made, \"something\" would compile the images and generate a site for reference. This tool came out of the desire for that \"something.\"\n\nTo get started, you will need a filesystem. Let's start with something like this:\n\n```bash\n./src\n-- index.md\n-- logo.png\n-- ./level1\n-- -- index.md\n-- -- user_flow.d2\n-- -- admin_flow.d2\n```\n\nBy running the tool with the proper flags (see the next section), you should end up with something like:\n\n```bash\n./build\n-- index.html\n-- logo.png\n-- ./level1\n-- -- index.html\n-- -- user_flow.svg\n-- -- admin_flow.svg\n```\n\nWhat happens is that the tool walks the filesystem target, compiles every .d2 file to an svg, compiles every Markdown file to an HTML file with the specified template, and copies any other file directly. In the Markdown files, {{filename}} will take the output `filename.d2` -\u003e `filename.svg` and convert it into an `\u003cimg\u003e` tag in the HTML.\n\nThe Markdown files can begin with YAML-based metadata. The currently accepted metadata are `title`, `summary`, and `tags`. For example:\n\n```markdown\n---\ntitle: Sample\ntags:\n  - tag1\n  - tag2\nsummary: A basic description, free of HTML, used for search.\n---\n\n# A sample page\n\n{{sample}}\n\n```\n\nThis will generate the title and tags as meta data, render the content as Markdown, and result in `{{sample}}` turning into `\u003cimg src='/sample.svg' alt='diagram' /\u003e`\n\n## Running the Tool\n\n```bash\n$ ./d2tosite -h\nNAME:\n   d2tosite\n\nUSAGE:\n    [global options] command [command options] [arguments...]\n\nDESCRIPTION:\n   A simple CLI that traverses a directory and generates a basic HTML site from Markdown and D2 files\n\nCOMMANDS:\n   help, h  Shows a list of commands or help for one command\n\nGLOBAL OPTIONS:\n   --config value            a config file that can be used to configure the build; if other flags are sent as well, they will override the file\n   --d2-theme value          the D2 theme ID to use (default: 1)\n   --input-directory value   the directory to read from and walk to build the site (default: \"./src\")\n   --output-directory value  the output directory to publish the site to (default: \"./build\")\n   --page-template value     the template to use for each page; if not provided, it will used the embedded template file at compile time\n   --index-template value    the template to use for the content of the diagram index; if not provided, it will used the embedded template file at compile time\n   --tag-template value      the template to use for each tag page content; if not provided, it will used the embedded template file at compile time\n   --clean                   if true, removes the target build directory prior to build\n   --continue-errors         if true, continues to build site after parsing and compiling errors are found\n   --help, -h                show help\n```\n\n## Configuration\n\nYou may choose to pass in a `.json` or `.yml` file as a configuration option. The extension will determine the parsing. Although there are many different naming conventions available, snake_case was chosen for simplicity. Effectively, the keys are just the binary command line options with `-` changed to `_`.\n\n## Templates\n\nTemplates are Go-style HTML templates that are applied to the compiled Markdown files. For an example, see the `./cmd/default_templates/page.html` file. Each template will be built with the `LeafData` filled out for that leaf AFTER all of the filesystem is walked. This is to ensure that each page can generate a navigation panel and search.\n\nEach template may be specified at the command line as an argument that is a relative-path. On start, the files will be checked to see if they exist. If they do not, embedded templates shipped with the binary at compile-time will be used. You can find a copy of them in the repo in `cmd/default_templates/*.html`.\n\n## Search\n\nSearch is a local index of pages keyed by their path with the content, title, tags, and summary indexed. It is then parsed through `lunr.js`. If the query param of `search` is present, the search content is displayed. Note that this is purely client-side and driven in the `page.html` template, so if you provide your own template, you will need to ensure you either support search as laid out or remove it from your site.\n\n## Roadmap\n\nThese are not in any specific order. If you are interested in working on, send a message or open an issue.\n\n[ ] GitHub actions to build binaries\n\n[ ] Dockerize the binaries for easier use\n\n[ ] Expose more D2 functionality\n\n[ ] Code cleanup to move beyond POC\n\n[ ] UI testing for HTML generation\n\n[ ] Logging and verbosity\n\n[ ] Add static page with output of the test data on main push\n\n[ ] Add output types of site (default), single-page (all on the same page, in order), or JSON (for consumption elsewhere)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkevineaton%2Fd2tosite","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkevineaton%2Fd2tosite","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkevineaton%2Fd2tosite/lists"}