Add a style guide to the blog contributing doc - #623
Closed
madolson wants to merge 10 commits into
Closed
Conversation
Adds an hourly workflow that releases blog posts marked draft = true once their frontmatter date has passed, by removing the draft line and committing to main. This lets maintainers merge posts ahead of time without them going live immediately. Uses Zola's native draft support, so pending posts are excluded from the build, blog listing, sitemap, and RSS feed until released. The workflow pushes with the valkeyrie-bot app token so the existing deploy workflow triggers on the resulting commit. This was generated by AI but verified, with love, by a human. Signed-off-by: Madelyn Olson <madelyneolson@gmail.com>
- Scope the app token with permission-contents: write, since the workflow permissions block only constrains GITHUB_TOKEN. - Stage content/blog directly instead of piping paths through xargs, which splits on whitespace and would break on filenames containing spaces. - Read and write with newline="" so CRLF-authored posts keep their line endings and produce a one-line diff. content/blog already contains one CRLF file, which previously would have been rewritten whole. Also strip the resulting lone trailing carriage return before parsing, which tomllib rejects. This was generated by AI but verified, with love, by a human. Signed-off-by: Madelyn Olson <madelyneolson@gmail.com>
Parse frontmatter entirely with tomllib. The regex module is no longer imported: the fences are found by string search, and each candidate line is validated by tomllib itself, which is what authoritatively distinguishes the real top-level 'draft = true' from one in a table, a comment, or a string. Quoted date values are re-parsed as bare TOML instead of a strptime loop, so both forms follow identical rules. This also fixes two files the regex mishandled: a post with a leading blank line before the fence, and one with a multi-line array in its frontmatter. Publish once a day at 16:00 UTC (08:00 PST / 09:00 PDT) instead of hourly. Posts are conventionally dated 00:00:00 or 01:01:01, so an hourly job would have published them in the middle of the night PT. Document that dates are UTC and that the time of day in 'date' does not control publication, and drop the suggestion that work-in-progress can be parked on main. This was generated by AI but verified, with love, by a human. Signed-off-by: Madelyn Olson <madelyneolson@gmail.com>
The publish job ignores the time of day, so a bare date is the clearer convention. 16 posts already use one. This was generated by AI but verified, with love, by a human. Signed-off-by: Madelyn Olson <madelyneolson@gmail.com>
This was generated by AI but verified, with love, by a human. Signed-off-by: Madelyn Olson <madelyneolson@gmail.com>
The line-scan approach had a real bug: a 'draft = true' inside a multi-line string was removed instead of the actual key, corrupting the value and leaving the post a draft. 8 existing posts use multi-line frontmatter values, so this was reachable. Now a candidate line is removed and the result re-parsed, accepting the edit only if it drops 'draft' and changes nothing else. Invalid TOML, a missing date, and an unparseable date now exit non-zero instead of warning and skipping. 'zola build' already fails on bad TOML, so there is no reason to accept it quietly here. This was generated by AI but verified, with love, by a human. Signed-off-by: Madelyn Olson <madelyneolson@gmail.com>
tomlkit is a round-trip TOML parser, so 'del frontmatter["draft"]' replaces the hand-rolled line scanning and the remove-then-re-parse verification. Reading the key directly only sees the top-level table, so the table-header scan is gone too, along with the multi-line-value corruption it was working around. Verified tomlkit round-trips all 59 existing posts byte-identically, and preserves comments and CRLF endings. Adds a pip install step; tomlkit is MIT with no dependencies. This was generated by AI but verified, with love, by a human. Signed-off-by: Madelyn Olson <madelyneolson@gmail.com>
This was generated by AI but verified, with love, by a human. Signed-off-by: Madelyn Olson <madelyneolson@gmail.com>
A post dated 2026-07-31 23:00:00 was held until the next day even though the docs say the time of day is ignored. Compare date() values instead, converting offset-aware datetimes to UTC first. Also align the frontmatter comment with the scheduling section: date is the publish date, not the day writing started. Signed-off-by: Madelyn Olson <madelyneolson@gmail.com>
Adds a 'How to write it' subsection to Step 2, matching the format of the existing tips list. The one-sentence-per-line rule is the functional one: GitHub anchors review suggestions to lines, so a paragraph written as a single long line forces every suggestion to restate the whole paragraph. The doc follows its own guidance. Signed-off-by: Madelyn Olson <madelyneolson@gmail.com>
Contributor
|
Important Review skippedDraft detected. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: Repository UI Review profile: CHILL Plan: Pro Plus Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Member
Author
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds a
How to write itsubsection to Step 2 of the blog contributing guide.It captures the style guidance reviewers already apply, so contributors can see it before the first review round rather than during it.
The one rule with a functional reason behind it is one sentence per line.
Markdown joins the lines back into a paragraph, so nothing changes about how a post renders.
It changes review: GitHub anchors suggestions to lines, so a reviewer can rewrite a single sentence instead of restating the whole paragraph, and two reviewers touching different sentences don't conflict.
The rest covers weasel words, checkable claims, benchmarking on stock Valkey, crediting contributors, marketing voice, active voice, headings, inclusive terminology, and formatting conventions.
The section follows its own guidance, so its source doubles as an example.