Automate frontmatter generation for easier contribution

[sirkitree]

Currently, contributors need to manually add frontmatter to their markdown files, which can be a barrier to contribution and lead to formatting issues. This was highlighted in PR #32 where the required frontmatter was missing.

Proposed Solution

Create an automated system to generate and add frontmatter to markdown files when they're submitted in a PR. This would make contributing easier and ensure consistent formatting.

Options to Consider

1. GitHub Action (Recommended)

• Automatically runs on PRs
• Extracts title from first H1 heading
• Generates description from first paragraph
• Sets date to PR creation date
• Determines discipline/contentType from file path
• Generates tags based on content analysis
• No setup required from contributors

2. Eleventy Transform

• Injects frontmatter during build if missing
• Works locally during development
• Might miss some metadata that could be extracted from PR context
• Requires build to see results

3. Pre-commit Hook

• Works locally before commit
• Requires setup from contributors
• May not have access to all context (like PR date)

4. Template Files

• Simple solution
• Requires manual copying
• No automation
• Could still be forgotten

Implementation Details for GitHub Action Approach

The action would:

1. Trigger on PR creation/update
2. Scan for new/modified .md files
3. Check for missing frontmatter
4. Generate frontmatter using:
   • Title: Extract from first H1 (# Title)
   • Description: Use first paragraph or generate from content
   • Date: PR creation date
   • Layout: Always "markdown.njk"
   • Discipline: Extract from file path
   • ContentType: Extract from file path
   • Tags: Generate based on content analysis

Questions to Consider

1. Should we auto-commit the changes or just comment on the PR?
2. How sophisticated should the tag generation be?
3. Should we validate the generated frontmatter against our requirements?
4. Should we provide a way for contributors to override the automation?

Next Steps

1. Choose preferred approach
2. Create proof of concept
3. Test with sample content
4. Document the automation process
5. Update contribution guidelines

Let's discuss which approach would work best for our team and contributors.

[sirkitree]

Another viable option to consider:

5. GitHub Issue Templates

• Create issue templates for each content type (prompts, workflows, etc.)
• Templates would include structured forms for all required frontmatter fields
• Contributors submit content via issues instead of direct PRs
• A maintainer or GitHub Action could then convert the issue content into properly formatted markdown files
• Benefits:
  • Familiar GitHub interface for contributors
  • Built-in validation through required form fields
  • No need for contributors to understand frontmatter syntax
  • Maintainers can review content before it becomes a PR
  • Could be combined with GitHub Actions to automate file creation
• Drawbacks:
  • Extra step in the process (issue → PR → merge)
  • May feel less direct than editing files
  • Contributors don't get immediate preview of how their content will look

This could be particularly user-friendly for non-technical contributors who are more comfortable with forms than markdown syntax.

[dsayswhat]

This is an interesting problem, gonna think out loud for a minute:

Issue templates, a google form, a discuss post, Slack thread are all just as likely to be the source of a good prompt that we want to include.

The trick, as you point out, is that maintainers will have to act as an intermediary in those cases... but maybe that's a good thing for consistency.

ADRs are a simlilar problem - we start in Discuss, Slack, or or really anywhere, and we've figured out over time how to publish them. Here we've solved for how to publish them, but still need to engage folks in the crafting of prompts in their work.

I wonder if we should embrace the idea of "invite and curate", under the idea that collecting prompts from anyone, rather than working to make this a self-serve machine, is the higher-value effort?

The publishing details aren't nearly as important as the prompts themselves, and escorting folks into the collection of prompts is the Be Human part of this anyway?

I feel like solving for "when and how are we collecting prompts" as widely as possible is really where we get successful, and the publication mechanism here is something we can continue to iterate on.

All that is to say I like the issue templates as middle ground for non-devs to join the process. Maybe my other takeaway is that we need to match this repo with efforts to collect prompts intentionally, so we can curate them here.

[mrdavidburns]

I like the "invite and curate" approach. Right now I just want people to share. We're in the knowledge transfer phase of this.
Much like people donate books to a library, it is still dependent on librarians to collect, organize, and properly place books where they belong.

So yes, if you see someone sharing prompts in other locations we should be collecting those here so we have a unified and organized (could be improved) way that people can look for prompts that fit their areas of expertise.

[sirkitree]

I've added a template for prompts - we can do one for each content type or update this one to generalize it for all content types, but let's start with prompts

Thoughts?