🗺️ Be able to export a Taskfile to markdown documentation w. mermaid dependency graph 📝

[adriens]

Description

❔ About

I use task a lot, and someimes, I feel the need to :

• ➿ Automate documentation (for example within a CI pipeline)
• 🗣️ Share a task file to non-programmers to explain them a workflow I implemented with task

👉 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;

Loading

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

[trulede]

You might find this PR interesting #2348, its possible to geneate documentation in any format you want - including MD Doc.

[adriens]

• Add templating support to CLI flags list/list-all #2348

[adriens]

You might find this PR interesting #2348, its possible to geneate documentation in any format you want - including MD Doc.

That inspired me @trulede

Made a first try and it seems like it's working , see
https://github.com/adriens/task-gomplates

[adriens]

I gave it a try on your taskfile (website) :

1. Download the Taskfile and the template file

   # Download the Taskfile
   curl -L https://github.com/go-task/task/raw/main/website/Taskfile.yml -o Taskfile.yml
   
   # Download the gomplate template
   curl -L https://github.com/adriens/task-gomplates/raw/main/tmpl/task-to-md-mermaid.gomplate -o task-to-md-mermaid.gomplate

2. Generate the Markdown Documentation

   gomplate -f task-to-md-mermaid.gomplate -d tasks=Taskfile.yml > Taskfile.md

See 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;

Loading

Task Goals and Descriptions

Task Name	Description
build	Build website
clean	Clean temp directories
default	Start website
deploy:next	Build and deploy next.taskfile.dev
deploy:prod	Build and deploy taskfile.dev
install	Setup VitePress locally
lint	Lint website
preview	Preview Website

[adriens]

Properly documented here

[trulede]

@adriens very cool!

not my site though 😉

[adriens]

@adriens very cool!

not my site though 😉

Do you have a taskfile to build yours ?

[adriens]

🚀

[ssbarnea]

TBH I am hoping @andreynering will agree to make this part of taskfile itself as I don't fancy adding a 3rd party repository dependency just to bake the taskfile dependency graph into my documentation building process.

[adriens]

🙏 💯