Introducing Markdown Builder – a GitHub Action that enables developers to generate rich markdown summaries directly from Handlebars templates with custom data. Whether you're posting updates to GitHub Actions summaries or adding comments on pull requests, Markdown Builder simplifies the process by allowing you to dynamically inject data into templates.
Check out the GitHub Markdown Builder on GitHub!
🌟 Why Markdown Builder?
Static markdown often doesn’t capture the full picture. For CI/CD workflows, test reporting, and documentation, dynamic markdown summaries that adapt to context and data are powerful. Markdown Builder allows you to create these adaptable summaries without extensive scripting by combining Handlebars templates with optional JSON data. Inspired by the GitHub Test Reporter, which allows users to build dynamic test reports, Markdown Builder brings similar flexibility to markdown any type of markdown summaries.
🔑 Key Features
- Easy Template Integration: Provide a Handlebars template, and Markdown Builder will render it for you.
- Dynamic Data: Pass JSON data to your template, enabling custom summaries tailored to your specific use case.
-
Flexible Posting Options: Choose where you want your markdown displayed:
- GitHub Action Summary: Perfect for summarizing key information within the workflow.
- Pull Request Comment: Great for adding context or test results directly on your PRs.
🛠 How It Works
1. Setup the Action
In your GitHub Actions workflow file, add a step for Markdown Builder. Here’s an example configuration:
- name: Generate Markdown Summary
uses: Ma11hewThomas/markdown-builder@v1
with:
template-file-path: './path/to/your/template.hbs'
json-file-path: './path/to/data.json' # Optional
summary: true # Set to true to post on GitHub Actions summary
pull-request: false # Set to true if you want it commented on the PR
2. Configure Your Inputs
Markdown Builder requires a template file, and you can optionally provide JSON data to fill in the template’s placeholders. Here’s what each input does:
template-file-path: Path to your Handlebars template file. This file will define the structure and layout of your markdown.
json-file-path (optional): Path to a JSON file that provides data to your template.
summary: If set to true, posts the rendered markdown to the GitHub Action summary.
pull-request: If set to true, comments the markdown on the associated pull request.
3. Customizing the Template with Handlebars
You can use any Handlebars syntax in your template to include data fields, loops, or conditional formatting. This makes Markdown Builder adaptable for a variety of scenarios, from summarizing test results to generating release notes.
# Build Summary
- Status: {{data.status}}
- Date: {{data.date}}
{{#each data.tests}}
- Test: {{name}} - Result: {{result}}
{{/each}}
4. See It in Action
After setting up the Action, you'll get instant, visually rich markdown output in your GitHub workflow summary or PR comments. No more manual updates or formatting struggles – Markdown Builder handles it all.
💡 Real-World Use Cases
Test Reporting: Automatically post test results as markdown on PRs to keep the team informed.
Build Summaries: Capture key build metrics or error logs right in the workflow summary.
Release Notes: Generate release summaries for stakeholders without manually formatting each item.
💬 Share Your Templates!
One of the great aspects of Markdown Builder is its flexibility with Handlebars templates. Whether you’re using it for test summaries, build metrics, or custom release notes, we’d love to see how you’re leveraging Markdown Builder in your workflows!
How to Share
If you’ve created a template that others might find useful, consider contributing it to the community templates section.
🤝 Support and Feedback
If you try Markdown Builder, we’d love to hear from you! Feel free to leave a GitHub star if you find it helpful, and don’t hesitate to reach out with feedback or ideas for enhancements.
Happy building! ✨
Top comments (0)