{"id":21033625,"url":"https://github.com/gabyx/technical-markdown","last_synced_at":"2025-07-08T04:04:35.107Z","repository":{"id":38206381,"uuid":"265353433","full_name":"gabyx/Technical-Markdown","owner":"gabyx","description":"Easy and full-automated markdown setup for technical documents. ","archived":false,"fork":false,"pushed_at":"2023-07-12T21:23:50.000Z","size":3914,"stargazers_count":116,"open_issues_count":4,"forks_count":7,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-05-15T13:44:03.743Z","etag":null,"topics":["gradle","html5","latex","less","pandoc","pandoc-citeproc","pandoc-crossref","pandoc-filters","pandoc-template","technical-documents","xelatex"],"latest_commit_sha":null,"homepage":"","language":"Less","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gabyx.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.md","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},"funding":{"github":["gabyx"]}},"created_at":"2020-05-19T20:07:01.000Z","updated_at":"2025-05-03T14:32:09.000Z","dependencies_parsed_at":"2024-11-19T13:08:40.647Z","dependency_job_id":null,"html_url":"https://github.com/gabyx/Technical-Markdown","commit_stats":null,"previous_names":[],"tags_count":25,"template":false,"template_full_name":null,"purl":"pkg:github/gabyx/Technical-Markdown","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gabyx%2FTechnical-Markdown","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gabyx%2FTechnical-Markdown/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gabyx%2FTechnical-Markdown/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gabyx%2FTechnical-Markdown/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gabyx","download_url":"https://codeload.github.com/gabyx/Technical-Markdown/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gabyx%2FTechnical-Markdown/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264192232,"owners_count":23570737,"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":["gradle","html5","latex","less","pandoc","pandoc-citeproc","pandoc-crossref","pandoc-filters","pandoc-template","technical-documents","xelatex"],"created_at":"2024-11-19T12:58:23.098Z","updated_at":"2025-07-08T04:04:35.092Z","avatar_url":"https://github.com/gabyx.png","language":"Less","funding_links":["https://github.com/sponsors/gabyx","https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick\u0026hosted_button_id=6S6BJL4GSMSG4"],"categories":[],"sub_categories":[],"readme":"# Technical Markdown\n\nA markdown setup for technical documents, reports, theses \u0026 papers.\n\n![](https://img.shields.io/badge/dependencies-docker%20%7C%20pandoc%20%7C%20python3%20%7C%20gradle%20%7C%20vscode-green)\n\n**History rewritten**: Due to LFS mistakes, `main` branch was rewritten and a\nreclone of this repository is needed.\n\n**Note: A `docker` build setup has been implemented! Read more in\n[here](#docker-build).**\n\nCheck the [`Changelog.md`](Changelog.md) for the latest changes.\n\n![Demo](docs/Demo.png)\n\n## Quick Intro\n\n**This is a markdown setup demonstrating the power and use of markdown for\ntechnical documents:**\n\n- **fully automated conversion sequence** using [`gradle`](https://gradle.org) +\n  [`pandoc`](https://github.com/jgm/pandoc) such that exporting\n  ([Content.md](https://raw.githubusercontent.com/gabyx/TechnicalMarkdown/master/Content.md))\n  is done in the background:\n\n  - **export to PDF** with `pandoc` to `xelatex` using `latexmk`\n    [See Output](docs/output/techmd/Content.pdf)\n  - **export to HTML** with `pandoc` to `html`\n    [See Output](https://gabyx.github.io/technical-markdown/docs/html-package/techmd/Content.html)\n  - [todo] **export to PDF** with `pandoc` to `html` then to `chrome` with\n    `pupeteer`\n\n- **[pandoc filters](https://pandoc.org/filters.html)** for different AST\n  (abstract syntax tree) conversions:\n\n  - [own filters](https://github.com/gabyx/TechnicalMarkdown/tree/master/tools/convert/filters)\n    with [panflute](https://github.com/sergiocorreia/panflute)\n    [[doc](http://scorreia.com/software/panflute)]\n  - [--crosscite](https://github.com/jgm/pandoc-citeproc)\n    [[doc](https://github.com/jgm/pandoc-citeproc/blob/master/man/pandoc-citeproc.1.md)]\n    for citing\n  - [pandoc-crossref](https://github.com/lierdakil/pandoc-crossref)\n    [[doc](http://lierdakil.github.io/pandoc-crossref)] for cross referencing\n  - [pandoc-include-files](https://github.com/pandoc/lua-filters/tree/master/include-files)\n    [[doc](https://github.com/pandoc/lua-filters/tree/master/include-files/README.md)]\n    for file transclusion\n\n- Full-fledged [VS Code](https://code.visualstudio.com/) setup to write and\n  style your document in one of the best IDEs (*nvim is better 😏*).\n\n## Quick-Start\n\nExecute the following in a shell:\n\n```shell\n./gradlew -t build-html\n```\n\nThis will build the HTML output from its [markdown main file](Content.md).\n\n## Demo Project\n\nThere is also a demo showing a [full thesis](https://github.com/gabyx/technical-markdown-demo) project.\n\n\n## Rational\n\n[Pandoc](https://github.com/jgm/pandoc) is awesome and the founder John\nMacFarlane develops pandoc in a meticulous and principled style. The\ndocumentation is pretty flawless and the community (including him) is really\nhelpful. That is why we rely heavily on pandoc.\n\n1. We target the output formats `html5` and `latex`, because\n\n   - HTML can be viewed in all browsers and web standards such as CSS3 etc. have\n     become a major advantage and enables ridiculuous dynamic, interactive\n     styling. Collapsable table of contents is just the beginning.\n   - LaTeX enables to produce high quality output PDF (`xelatex`). Every proper\n     book and distributed PDF is written and set in LaTeX.\n\n2. The orchestration around calling `pandoc` is basically only a file watcher\n   [`gradle`](https://gradle.org) which calls `pandoc` on file changes. We want\n   as little as possible different tools to achieve the above output formats.\n   That also means we _do not want_ to have lots of pre- and post-processing\n   tasks aside from running `pandoc`. The main goal is, that users can write\n   `markdown` as a **first-party solution** with some enhanced features enabled\n   by `pandoc` itself. **Writting technical documents should become a breeze.**\n\n3. The common agreement in the industry about using M$ Office for writting\n   technical documentations as demonstrated here, is considered the most\n   complete and utter bullshit you can adhere to. Certainly employees mostly\n   must obey. The common argument is \"people need to exchange documents and work\n   on it\". experiences, a lot of time and money is spent which gets never\n   debated.\n\n   **It's about high time** to turn into a direction which will likely become\n   the standard. **Technical writters should really focus on the content they\n   write and not focus on styling quirks and tricks.**\n\n4. Every technical document writter probably knows about source code management\n   (`git`). There you go with proper team work.\n\n## Project Layout\n\nThe following directories of a single project in [`src`](src) (e.g.\n[`src/techmd`](src/techmd)) are important for the content of the output:\n\n- [`Content.md`](Content.md) : The main markdown document.\n- [`chapters`](chapters) : All markdown source included in the\n  [main markdown docucment](Content.md).\n- [`files`](files) : All additional files referenced in the markdown documents\n  in [`chapters`](chapters).\n- [`literature`](literature) : All bibliography/literature related files (e.g.\n  [`bibliography.bib`](literature/bibliography.bib)).\n- [`includes`](includes) : Special include files (e.g.\n  [MathJax definitions](includes/Math.html)) and other project related build\n  tooling files which act as input files to the `pandoc` build process.\n\nThe following directories are important for the styling of the output:\n\n- [`tools/convert`](tools/convert) : The main _tools_ directory containing\n  pandoc related output configs. It acts as pandocs\n  [`data-dir`](https://pandoc.org/MANUAL.html#option--data-dir). See\n  [env. variables](#environment-variables) in docker builds.\n\n  - [`tools/convert/defaults`](tools/convert/defaults) : `pandoc` defaults .\n  - [`tools/convert/includes`](tools/convert/includes) : `pandoc` templates in\n    for HTML and PDF output settings.\n  - [`tools/convert/css`](tools/convert/css) CSS styling for HTML output.\n  - [`tools/convert/filters`](tools/convert/filters) : `pandoc` filters in for\n    modifying `pandoc`s abstract syntax tree.\n  - [`tools/convert/scripts`](tools/convert/scripts) : Some workaround scripts\n    for converting tables based on a config file in\n\n## Dependencies\n\nIf you have `docker`, you should directly open this project in VS Code with the\nprovided `.devcontainer` setup which gives you a hassle free experience. See\n[Docker Setup](#docker-build) for more information. Building on a native system,\nyou need the following dependencies:\n\n### Gradle\n\nFor the Gradle build tool you need a working [Java runtime](https://java.com).\nOn Linux and macOS you can do:\n\n```shell\nbrew install java\n```\n\nYou should not need to install Gradle, since everything is setup by the\nchecked-in `gradlew` Gradle wrapper.\n\n### Yarn\n\nSo far `yarn` is not required on the system and handled by the dependent Gradle\ntask `yarnSetup`. If you experience problems with having the node modules not\ncorrectly setup, use\n\n```shell\ncd tools\n../build/techmd/yarn/bin/yarn install --modules-path build/techmd/node_modules\n```\n\n### Pandoc\n\nInstall [pandoc](https://pandoc.org/installing.html) (\u003e= 2.9.2.1, tested with\n2.16.2)\n\nFor **Linux** and **macOs**:\n\n```shell\nbrew install pandoc pandoc-crossref\n```\n\nFor **Windows**:\n\n```shell\nchoco install pandoc\n```\n\n### Python\n\nInstall a recent `python3` (\u003e= 3.9) and the following packages.\n\nSetup a python environment in `.venv` with\n`python -m venv --system-site-packages ./.venv` and install the packages:\n\n```shell\npython -m venv --system-site-packages .venv # or simply symlink to an existing one.\nsource .venv/bin/activate\npip3 install -r tools/docker/setup/python.requirements\n```\n\nThe VS Code tasks pass the config `${config:python.pythonEnv}` directly as an\nargument to `gradlew` (if not set `python` is the default). The tasks are run in\na shell where `./.venv/bin/activate` has been called. Then, `pandoc` will use\nthe correct python when launching the filters.\n\nYou can also use the ignored [.envrc](.envrc) file with\n[direnv](https://github.com/direnv/direnv).\n\n## Building and Viewing\n\nRun the following tasks defined in [tasks.json](.vscode/tasks.json) from VS Code\nor use the following shell commands:\n\n- **Show HTML Output**: Serves the HTML for preview in a browser with\n  autoreload:\n\n  ```shell\n  ./gradlew -t view-html\n  ```\n\n- **Convert Markdown -\u003e HTML**: Runs the markdown conversion with Pandoc\n  (`html`) continuously:\n\n  ```shell\n  ./gradlew -t build-html\n  ```\n\n  - The conversion with pandoc applies the following filters in\n    [defaults](tools/convert/defaults/pandoc-filters.yaml).\n  - The HTML output can be inspected in `Content.html`.\n\n- **Convert Markdown -\u003e PDF**: Runs the markdown conversion with Pandoc\n  (`latexmk` and `xelatex`) continuously:\n\n  ```shell\n  ./gradlew -t build-pdf-tex\n  ```\n\n  - The conversion with pandoc applies the following filters in\n    [defaults](tools/convert/defaults/pandoc-filters.yaml).\n  - The PDF output can be inspected in [`Content.pdf`](build/Content.pdf).\n  - The LaTeX output can be inspected in `build/output-tex/input.tex`.\n\n- **Convert Markdown -\u003e Jira**: Runs the markdown conversion to Jira\n  (experimental) with Pandoc continuously:\n\n  ```shell\n  ./gradlew -t build-jira\n  ```\n\n  - The conversion with pandoc applies the following filters in\n    [defaults](tools/convert/defaults/pandoc-filters.yaml).\n  - The Jira output can be inspected in `Content.jira`.\n\n## Docker Build\n\nWe provide 2 images based on `pandoc/latex:2.18-alpine` in\n[gabyxgabyx/technical-markdown](https://hub.docker.com/r/gabyxgabyx/technical-markdown):\n\n1. [**`gabyxgabyx/technical-markdown:latest-minimal`**](https://hub.docker.com/r/gabyxgabyx/technical-markdown/tags)\n   : Minimal docker images including pandoc and all necessary tools to fully\n   build your markdown. It does not include the folder `tools` and `convert` and\n   your mounted Git repository needs to contain these as in this repository or\n   by setting the environment variables described below. This is useful if you\n   want to tweak the layout and styling of the document.\n2. [**`gabyxgabyx/technical-markdown:latest`**](https://hub.docker.com/r/gabyxgabyx/technical-markdown/tags)\n   : The full-fledged image which is used in this VS Code `.devcontainer` setup.\n   It contains its baked `tools` and `tools/convert` folders which are used to\n   compile your markdown.\n\nThe `\u003cversion\u003e` above corresponds to either `latest` or the Git version tag\nminus the `v` prefix.\n\n### Environment Variables\n\nNumbers refer to the container images above:\n\n| Env. Name                | Default Value                                       | Description                                                                                     |\n| ------------------------ | --------------------------------------------------- | ----------------------------------------------------------------------------------------------- |\n| `TECHMD_TOOLS_DIR`       | 1. not set                                          | The tools directory containing all files needed for the conversion.                             |\n|                          | 2 . `/home/techmd/technical-markdown/tools`         |                                                                                                 |\n| `TECHMD_CONVERT_DIR`     | 1. not set                                          | The convert directory containing the files needed for the `pandoc` converstion.                 |\n|                          | 2 . `/home/techmd/technical-markdown/tools/convert` |                                                                                                 |\n| `TECHMD_USE_SYSTEM_NODE` | 1. `true`                                           | Use the node installation on the system instead of installing a local one into the build folder |\n|                          | 2. `true`                                           |                                                                                                 |\n\n### Using the Docker Image\n\nEither copy the `.devontainer` to your project (you don't need the `tools`\nfolder) and open the project in the VS Code remote container extension.\n\nAlternatively you can always use:\n\n```shell\ndocker run -v \"\u003cpath-to-your-repo\u003e:/workspace\" \\\n    gabyxgabyx/technical-markdown:latest\"\n    ./gradlew build-html\n```\n\n### Extending the Technical-Markdown Docker Images\n\nIf you need special other tools and an other setup which might be useful for the\ngeneral images above, consider submitting an issue. Otherwise you can always\nextend the existing images for [layout/styling](#editing-styles) changes with\nanother Dockerfile like:\n\n```dockerfile\nFROM gabyxgabyx/technical-markdown:latest-minimal as mycustomtechmd\n// More Dockerfile commands ...\n```\n\n### Building the Technical-Markdown Docker Images\n\nTo build the images in this repository for customization use:\n\n```shell\ntools/docker/build.sh \\\n    --base-name \"mycustomimage\" \\\n    [--push-base-name \"docker.io/superuser\"] \\\n    [--push]\n```\n\n## Editing Styles\n\n### HTML\n\nYou can edit the [main.less](tools/convert/css/src/main.less) file to change the\nlook of the markdown. Edit the [main.less](tools/convert/css/src/main.less) file\nto see changes in the conversion from [Content.md](Content.md).\n\n### LaTeX\n\nThe following templates are responsible for the LaTeX output:\n\n- [Template.tex](tools/convert/includes/Template.tex) : The main template.\n- [Header.tex](tools/convert/includes/Header.tex) : The class, packages and\n  styles defining the document, included by the main template with\n  `include-in-header` in\n  [pandoc-latex.yaml](tools/convert/defaults/pandoc-latex.yaml)\n\n### Pandoc Filters\n\nPandoc filters are harder to debug. There is an included unix-like\n[tee.py](tools/convert/filters/tee.py) filter which can be put anywhere into the\nfilter chain as needed, to see the AST JSON output in the folder\n`build/pandoc-filter-out` (see [dev.py](tools/convert/filters/module/dev.py) for\nadjustments). The filter [teeStart.py](tools/convert/filters/teeStart.py) first\nclears all output before doing the same as\n[tee.py](tools/convert/filters/tee.py). Uncomment the `tee.py` filters in\n[pandoc-filters.yaml](tools/convert/defaults/pandoc-filters.yaml).\n\n## Issues\n\n### Panflute [done]\n\nUsing pandoc `\u003e=2.10` we have more types and AST changes in\n\n- [jgm/pandoc#1024](https://github.com/jgm/pandoc/issues/1024),\n- [jgm/pandoc#6277](https://github.com/jgm/pandoc/pull/6277),\n- [2.10](https://github.com/jgm/pandoc/releases/tag/2.10)\n\nmeaning that also the python library `panflute` needs to be supporting this:\n\n- [Issue](https://github.com/sergiocorreia/panflute/issues/142) :\n  ![](https://img.shields.io/badge/dynamic/json?color=%23FF0000\u0026label=Status\u0026query=%24.state\u0026url=https%3A%2F%2Fapi.github.com%2Frepos%2Fsergiocorreia%2Fpanflute%2Fissues%2F142)\n\n### Transclude: Relative file paths [done]\n\nSo far _relative_ paths are not yet supported in `pandoc-include-files.lua`\nfilter.\n\n- [Issue](https://github.com/pandoc/lua-filters/issues/102) :\n  ![Status](https://img.shields.io/badge/dynamic/json?color=%23FF0000\u0026label=Status\u0026query=%24.state\u0026url=https%3A%2F%2Fapi.github.com%2Frepos%2Fpandoc%2Flua-filters%2Fissues%2F102)\n\n### Table Issues [done]\n\n- Wrong format for `latex`: [Issue](https://github.com/jgm/pandoc/issues/6883) :\n  ![Status](https://img.shields.io/badge/dynamic/json?color=%23FF0000\u0026label=Status\u0026query=%24.state\u0026url=https%3A%2F%2Fapi.github.com%2Frepos%2Fjgm%2Fpandoc%2Fissues%2F6883)\n  -\u003e Update to next version.\n\n## Todo\n\n- Add CI.\n- Add tests.\n- Add prince conversion to PDF.\n\n## Support \u0026 Donation\n\nWhen you use Githooks and you would like to say thank you for its development\nand its future maintenance: I am happy to receive any donation:\n\n[![paypal](https://www.paypalobjects.com/en_US/i/btn/btn_donate_LG.gif)](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick\u0026hosted_button_id=6S6BJL4GSMSG4)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgabyx%2Ftechnical-markdown","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgabyx%2Ftechnical-markdown","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgabyx%2Ftechnical-markdown/lists"}