Repository navigation
🗺️ Be able to export a Taskfile to markdown documentation w. mermaid dependency graph 📝 #2503
Description
Description
❔ About
I use task a lot, and someimes, I feel the need to :
- ➿ Automate documentation (for example within a CI pipeline)
- 🗣️ Share a
taskfile to non-programmers to explain them a workflow I implemented withtask
👉 I only need to export a kind of javadoc or taskdoc
💡 The idea
In addition to --list option, would it possible to add the --markdown option so we could get that kind of md output :
Taskfile Workflow Diagram
This diagram visualizes the dependencies and flow between tasks defined in Taskfile.yml :
graph TD
default["**default**"]:::defaultNode -- deps --> generate["generate"]
default -- deps --> generate-webp["generate-webp"]
default -- deps --> optimize["optimize"]
generate -- deps --> setup["setup"]
clean["clean"]
pdf-logo["pdf-logo"]
classDef defaultNode fill:#1976D2,color:#fff,stroke:#333,stroke-width:2px;
Task Goals and Descriptions
| Task Name | Description |
|---|---|
| default | This Taskfile dynamically creates PNG and JPEG image assets from SVG source files. Run 'task generate' to create them. |
| setup | Check for required tools (svgexport, convert, optipng, jpegoptim) |
| generate | Generate PNG and JPEG versions of the logos from SVG files |
| clean | Remove all generated files |
| pdf-logo | Compile the LaTeX logo into a PDF and clean up auxiliary files |
| generate-webp | Generate WebP versions of the logos from PNG files |
| optimize | Optimize the size of generated PNG and JPEG files |
Copy and paste the Mermaid code into a Markdown viewer that supports Mermaid to see the graph rendered visually.
🔭 Further with dot / graphviz option
Like terraform makes it possible, maybe add the option to export to dot / graphviz
Activity
[-]🗺️ Be able to export a Taskfile to `markdown` documentation w. `mermaid` dependcy graph[/-][+]🗺️ Be able to export a Taskfile to `markdown` documentation w. `mermaid` dependency graph[/+][-]🗺️ Be able to export a Taskfile to `markdown` documentation w. `mermaid` dependency graph[/-][+]🗺️ Be able to export a Taskfile to `markdown` documentation w. `mermaid` dependency graph 📝 [/+]trulede commentedon Nov 10, 2025
You might find this PR interesting #2348, its possible to geneate documentation in any format you want - including MD Doc.
adriens commentedon Nov 11, 2025
Create task-to-md-mermaid.gomplate
adriens commentedon Nov 12, 2025
That inspired me @trulede
Made a first try and it seems like it's working , see
https://github.com/adriens/task-gomplates
adriens commentedon Nov 12, 2025
I gave it a try on your taskfile (website) :
Download the Taskfile and the template file
Generate the Markdown Documentation
gomplate -f task-to-md-mermaid.gomplate -d tasks=Taskfile.yml > Taskfile.mdSee by yourself below 👇
Taskfile Workflow Diagram
This content was generated thanks to adriens/task-gomplates.
This diagram visualizes the dependencies and flow between tasks defined in
Taskfile.yml:graph TD build[build] clean[clean] default["**default**"]:::defaultNode deploy:next[deploy:next] deploy:prod[deploy:prod] install[install] lint[lint] preview[preview] build -- deps --> install default -- deps --> install lint -- deps --> install preview -- deps --> build classDef defaultNode fill:#1976D2,color:#fff,stroke:#333,stroke-width:2px;Task Goals and Descriptions
buildcleandefaultdeploy:nextdeploy:prodinstalllintpreviewadriens commentedon Nov 12, 2025
Properly documented here
trulede commentedon Nov 12, 2025
@adriens very cool!
not my site though 😉
adriens commentedon Nov 12, 2025
Do you have a taskfile to build yours ?