{"id":13311729,"url":"https://github.com/larseggert/i-d-toolchain","last_synced_at":"2025-04-30T20:30:29.978Z","repository":{"id":49255933,"uuid":"336216862","full_name":"larseggert/i-d-toolchain","owner":"larseggert","description":"A docker image with all the tools installed that kramdown-rfc2629 might need.","archived":false,"fork":false,"pushed_at":"2021-11-23T08:05:29.000Z","size":563,"stargazers_count":5,"open_issues_count":0,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2023-03-01T17:41:57.638Z","etag":null,"topics":["i-d","ietf","internet-draft","kramdown","markdown","rfc","rfc2629"],"latest_commit_sha":null,"homepage":"","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"unlicense","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/larseggert.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}},"created_at":"2021-02-05T08:57:56.000Z","updated_at":"2022-10-01T18:14:42.000Z","dependencies_parsed_at":"2022-09-15T21:31:14.463Z","dependency_job_id":null,"html_url":"https://github.com/larseggert/i-d-toolchain","commit_stats":null,"previous_names":[],"tags_count":null,"template":null,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/larseggert%2Fi-d-toolchain","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/larseggert%2Fi-d-toolchain/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/larseggert%2Fi-d-toolchain/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/larseggert%2Fi-d-toolchain/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/larseggert","download_url":"https://codeload.github.com/larseggert/i-d-toolchain/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224223056,"owners_count":17276115,"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":["i-d","ietf","internet-draft","kramdown","markdown","rfc","rfc2629"],"created_at":"2024-07-29T18:02:29.155Z","updated_at":"2024-11-12T05:27:15.696Z","avatar_url":"https://github.com/larseggert.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"# i-d-toolchain\n\nThis repository provides a docker image with all the tools installed that\n[kramdown-rfc2629](https://github.com/cabo/kramdown-rfc2629) might need.\nMany other relevant tools are also installed in the image,\n[see below](#installed-components). This makes it possible to generate the\nXML and other desired formats for Internet-Drafts without installing any\nlocal tools, except of course docker.\n\n**NEW!** You can now convert your I-D sources via a web user interface\nrunning inside the container, in a drag-and-drop fashion. No need to\nexecte shell commands! [Details below.](#via-a-web-ui)\n\nThis is free and unencumbered software released into the public domain.\n\n## Usage\n\nThere are two ways for executing commands in this Docker image, via the\n`i-d-toolchain` bash script, and directly from your shell. The former is\nrecommended.\n\n### Via the `i-d-toolchain` bash script\n\nFirst, download and install the `i-d-toolchain` bash script into a convenient\nlocation, such as `$HOME/bin`:\n```shell\ncurl --output $HOME/bin/i-d-toolchain \\\n     https://raw.githubusercontent.com/larseggert/i-d-toolchain/main/i-d-toolchain\nchmod a+x $HOME/bin/i-d-toolchain\n```\n\nYou can then run commands in the i-d-toolchain Docker container on files inside\nthe current directory like this:\n```shell\ni-d-toolchain kdrfc -h -3 draft-i-d-toolchain-test-00.md\n```\n\nIn the example above, `kdrfc` would execute inside the Docker container on the\n`draft-i-d-toolchain-test-00.md` in the local directory, producing text and HTML\nversions of the `draft-i-d-toolchain-test-00.md` Markdown document. `kdrfc` can\nbe replaced by any other command installed in side the image, as desired.\n\nYou can run `i-d-toolchain -u` to update both the `i-d-toolchain` script and the\nunderlying Docker image. Please do so occasionally, to keep using the latest\ntoolchain.\n\n### Directly from your shell\n\nThe `i-d-toolchain` bash script is basically a simple wrapper that passes the\ngiven command into a rather convoluted `docker run` incantation. You can also\nexecute this directly from the shell, but it is cumbersome.\n\nIn order to replicate the `i-d-toolchain kdrfc -h -3\ndraft-i-d-toolchain-test-00.md` example from above, you would need to execute\nthis `docker run` command:\n``` shell\ndocker run \\\n       --pull always \\\n       --volume $(pwd):/id:delegated \\\n       --env XML2RFC_REFCACHEDIR=/id/.cache/xml2rfc \\\n       --env KRAMDOWN_REFCACHEDIR=/id/.cache/xml2rfc \\\n       --interactive \\\n       --tty \\\n       --cap-add=SYS_ADMIN \\\n       ghcr.io/larseggert/i-d-toolchain:latest \\\n       kdrfc -h -3 draft-i-d-toolchain-test-00.md\n```\n\nMake sure the test markdown document exist in your local directory.\n\nHere is a breakdown of what the components of this rather long command are:\n\n* `docker run` executes a given command in a given docker container\n\n* `--volume $(pwd):/id:delegated` mounts the current directory into the docker\n  container at the `/id` mount point. The name of the `/id` mount point **must\n  not** be changed, since it is tied to where various caches are being kept. The\n  `:delegated` can be omitted, but provides a minor speed-up.\n\n* `--pull always` makes sure that the latest published version of the docker\n  image provided in this repository is used. This can be omitted, e.g., when\n  running without Internet connectivity, but then `docker pull` should be\n  occasionally run to update the image.\n\n* `--env` passes various environment variables to the tools of the Docker\n  container, that makes them create and use caches in the local directory.\n\n* `--interactive` keeps `stdin` attached for the session\n\n* `--tty` allocates a pseudo-TTY for the session\n\n* `--cap-add=SYS_ADMIN` is needed when the draft markdown contains artwork that\n  relies on `mermaid` for processing. It can be omitted in other cases, but\n  there is no harm in always passing it.\n\n* `ghcr.io/larseggert/i-d-toolchain:latest` is the name of the docker image to\n  be run.\n\n* Finally, you can specify a command to run inside the container for some\n  file(s) in the current working directory. In this example, we execute\n  ``` shell\n  kdrfc -h -3 draft-i-d-toolchain-test-00.md\n  ```\n  which runs `kdrfc` from\n  [kramdown-rfc2629](https://github.com/cabo/kramdown-rfc2629) in order to\n  convert the markdown document `draft-i-d-toolchain-test-00.md` in the current\n  working directory to text and HTML. This can be replaced by any other command\n  installed in side the image, as desired.\n\nAlso see the `docker run --help` information, and check the end of the\n`i-d-toolchain` bash script for any changes to this incantation that might not\nhave been reflected in this README.\n\n## Via a web UI\n\nTo use a web frontend to convert I-D sources to HTML, text or PDF versions, do\n``` shell\ndocker run \\\n       --pull always \\\n       --publish 8000:8000 \\\n       --cap-add=SYS_ADMIN \\\n       ghcr.io/larseggert/i-d-toolchain:latest\n```\n\nand then open http://localhost:8000/ in your browser.\n\n## Installed components\n\nThese are the tools that are currently installed in this image:\n\n* [kramdown-rfc2629](https://github.com/cabo/kramdown-rfc2629) and its\n  optional dependencies:\n  * [goat](https://github.com/blampe/goat)\n  * [ditaa](https://github.com/stathissideris/ditaa)\n  * [mscgen](http://www.mcternan.me.uk/mscgen/)\n  * [plantuml](https://plantuml.com)\n  * [mermaid](https://github.com/mermaid-js/mermaid-cli)\n  * [tex2svg](https://github.com/mathjax/mathjax-node-cli)\n  * [asciiTeX](https://github.com/larseggert/asciiTeX)\n  * [kgt](https://github.com/katef/kgt)\n  * [protocol](https://www.luismg.com/protocol/)\n  * [aasvg](https://github.com/martinthomson/aasvg)\n* [mmark](https://github.com/mmarkdown/mmark)\n* [idnits](https://tools.ietf.org/tools/idnits/)\n* [rfcdiff](https://tools.ietf.org/tools/rfcdiff/)\n* [rfcmarkup](https://tools.ietf.org/tools/rfcmarkup/)\n* [ietf-reviewtool](https://github.com/larseggert/ietf-reviewtool)\n* [svgcheck](https://pypi.org/project/svgcheck/)\n\nPull requests adding additional tools to the toolchain are appreciated!\n\n## Common errors\n\n* In case you see the \"no basic auth credentials\" error\n  ```\n  docker: Error response from daemon: Head https://ghcr.io/v2/larseggert/i-d-toolchain  /manifests/latest: no basic auth credentials\n  ```\n  you need to `docker login`, using your GitHub user name and a personal\n  access token as the password. The token needs to have at least the\n  `read:packages` scope, and [can be generated\n  here](https://github.com/settings/tokens/new).\n\n  ``` shell\n  docker login -u $GITHUB_USERNAME -p $GITHUB_TOKEN ghcr.io\n  ```\n\n* If you are able to run docker, but see something similar to\n  ```\n  `read': No such file or directory @ rb_sysopen - draft-i-d-toolchain-test-00.md (Errno::ENOENT)\n  from /usr/lib/ruby/gems/2.7.0/gems/kramdown-rfc2629-1.3.37/bin/kramdown-rfc2629:320:in `\u003ctop (required)\u003e'\n  from /usr/bin/kramdown-rfc2629:23:in `load'\n  from /usr/bin/kramdown-rfc2629:23:in `\u003cmain\u003e'\n  *** kramdown-rfc failed, status 1\n  ```\n  the given file (here, `draft-i-d-toolchain-test-00.md`) is not present in the\n  current working directory.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flarseggert%2Fi-d-toolchain","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flarseggert%2Fi-d-toolchain","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flarseggert%2Fi-d-toolchain/lists"}