playing with child qmd files as rules

[sckott]

Description

Per our conversations, playing here with using child .qmd files to organize rules that we want to track/use/etc.

Related Issue

#37

Example

I've only done this in one chapter: Package maintenance, open that up and scroll down towards the bottom.

Testing

N/A

Discussion

We could not use callouts too. We could instead do:

• Just plain text of the rule in a child qmd file, then include it
• Something other than callouts that's not plain text?

Advantages of callouts:

• It's easy for humans to find rules when they are reading a chapter

Disadvantages of callouts:

• Does it look awkward having callouts throughout?
• Maybe callouts won't always work? e.g. may want a list of 10 rules, and then it'd be 10 callouts in a row.

In terms of machine reading, e.g.,

pak::pak("rundel/parsermd")
library(parsermd)

z <- parse_qmd("rules//main-branch.qmd")
z
#> └── Open Fenced div [.callout-note, icon=false]
#>     └── Heading [h2] - {{< iconify carbon rule-draft >}} Rule
#>         └── Markdown [1 line]
#>         └── Close Fenced div

rmd_select(z, has_type("rmd_markdown")) %>% as_document(collapse = "")
#> [1] "Every project should have a `main` branch which contains the most 
#> stable version of the software, or the version of the software that 
#> corresponds to the most recent release of the software."

That's just a quick example in R, could do in python too.

[github-actions]

🚀 Deployed on https://deploy-preview-38--monumental-cassata-2f9bb7.netlify.app

[seankross]

I LOVE this! Full support, I think the implementation is right. I say ship it.

[sckott]

Thanks @seankross - Let me know what you think @tefirman

[sckott]

p.s. I can't ship this as is, as this is just for one chapter. I'll do the rest adding to this PR, then can merge once its all set

[github-actions]

🚀 Deployed on https://deploy-preview-38--monumental-cassata-2f9bb7.netlify.app

[sckott]

@seankross can you look at this again (see preview link above)? I changed my mind about how to organize and display rules. callouts were kinda cool but take up a lot of space and have to be on their own lines (can't be in a list, etc.) and most of of our rules are naturally falling within a markdown list of things, so after a bit of trial and error, looks like quarto var shortcocdes https://quarto.org/docs/authoring/variables.html#var might be our best option.

I've reworked the rules using var shortcodes, with the following highlights:

• All rules are now in a _variables.yml file in the root of the repo https://github.com/getwilds/guide/pull/38/files#diff-8d85c8bb2b6fc2aa55722bcd0dd3fd43b81e6ccdbd0fe7eefbd900609c63875d It would be easy to fetch and parse that file to do whatever needed with it
• Rules are pulled into the text anywhere you want them.
• I made a yml field for the bootstrap badge with the shield icon so we can reference that instead of being repeated in every rule
• a rule can now be referenced like {{< var rule-badge >}} {{< var rules.release-tags >}}
• we could in the future add a link to the badge so a reader could go to another page/repo for more information on that rule - perhaps how we check it
• The single place where the badge and icon are defined too makes it easy to tweak those in one place and ripples out to all uses of it

---

Thoughts?

[seankross]

I like this too! Full endorsement and full speed ahead.

[sckott]

Thanks Sean, merging and we'll continue to iterate from here