How to Contribute to the Newsletter
How to Contribute to the Newsletter
Writing the newsletter from scratch each month can become quite cumbersome, especially when juggling numerous demands and edits, optional/conditional sections, and lists of criteria that can change at the last minute.
Being programmers, we elect to do this programmatically using
Quarto and Liquid Templating. Instead of one monolithic document,
each section is its own markdown file that gets included based on
a template file template.qmd. To include/exclude a section,
simply set the truthy/falsy value in params.yml. Included in
params.yml is metadata that will feed into any site specific data
such as the header image, the title and subtitle, image alt text,
and the meeting date for the next community call.
Requirements
A single installation of Quarto on your local machine will install both of the above.
Data Driven Sections
We elect to have numerous sections of the newsletter generated by data,
parsed and rendered using Liquid Templating Langauge. All data is stored
in _data.
| Section | Quarto Source MD | _data Source File | _includes HTML snippet |
|---|---|---|---|
| Images & Alttext | params.yml | /assets/img/newsletter-[YYYYMM]/[FILENAME.ext] | NA |
| Organizational founding membership | _orgmember.md | _org-members.yaml | NA |
| Events | _events.md | _newsletter-events-opportunities.yml | event-box.html, opportunity-box.html |
| Reads | _reads.md | Export Zotero Bibliography as newsletter_bib.bib | citation.hml, citation-podcast.html, citation-publication.html |
| Working Group involvement | _involved.md | menus/working-groups.yml | NA |
| Jobs | _jobs.md | jobs.yml, job-boards.yml | NA |
We include a bash script that will do the majority of the work for us.
First, it uses quarto to render the template MD file.
Second, it converts your exported newsletter bibliography from .bib to
.yml for Liquid parsing using pandoc. Importantly, we make use of the Reading List
Zotero plugin to keep track of publications that have already gone out —
anything that we want in the upcoming edition is flagged as To Read, which
is the exact string Liquid parses the Yaml metadata for. The Interesting
Reads section is configured for anything that exports as article-journal (most
journal articles, preprints, and reports), song (podcast episodes), and
webpage (Blog posts, web screengrabs, other reports) in the type section.
Lastly, it inserts the yaml metadata necessary for Jekyll to recognise the
final output markdown file as a post. The bash script render_new_edition.sh
can be used to do each of these steps.
For each new edition, review params.yml, and for each section,
decide whether it will be included by changing
the flag from false to true, and filling in the corresponding markdown file.
Review the Slack for events and opportunities, filling them in under
_newsletter-events-opportunities.yml (taking careful note of the expiration date).
Additionally, review the Slack for publications, using Zotero to
catalog them (including changing the publication type to one of the approved
items above).Add in the publication data and an image, and export your
bibliography from Zotero to .bib, and when you’re ready to publish,
run ./render_new_edition.sh.
Limitations:
Currently, there are two known limitations of this approach:
- The generated Table of Contents no longer adds correct hyperlinks, because our headers often contain emojis
- The Table of Contents is misplaced; you must manually copy and paste it in the final version so that it appears under the preamble.
Other checks that should be made (that could be automated):
- Orgmember join date
- Community funds deadline
- Community call youtube thumbnail update