Between Two Parens

• Housekeeping
• Quickstart
• Project Commands
• Upgrade Dependencies
• Blog Post Guidelines
  • Frontmatter
  • Images
  • Article Notes
  • Footnotes
  • Updating Blog Posts
  • Updating Blog Checklist
• Blog Features
• Before Dev
• Before Deploy
• Writing Style Guide
• Special Thanks
  • Design
  • Illustrations
  • Content

Housekeeping

Be sure to have the following tools installed

• Node
• Yarn

Quickstart

• Create a project directory

  mkdir your-project-name

  your-project-name is whatever you choose to name your project

• Move into your project directory

  cd your-project-name

• Clone this repo into your project directory

  git clone https://github.com/athomasoriginal/eee-o-eleven.git .

  The . at the end of the above command clones the projects root dirs/files

• Move into the project directory

  cd your-project-name

  You may want to even rename this directory while your at it

• Install project dependencies

  yarn install

  Wait for everything to install before running the next step

• Create a file called .env

  CMS_URL="<fill-in-with-prismic-stuffs>"

  create in the root of your repo

• Start the project

  yarn run dev

Project Commands

• Run development environment

  yarn run dev

• Run development environment in debug mode

  yarn run dev:debug

• Build for production

  yarn run build

Upgrade Dependencies

Quick note: package.json dependencies are exact versions to prevent accidental bumps. Yes, JS land is error prone.

• Find outdated packages

  yarn outdated

• Upgrade a specific package in package.json

  yarn upgrade --latest <package-name>

  Above is fine if you want to upgrade to latest and to have the package.json also updated.

• Upgrade all packages matching a pattern in package.json

  yarn upgrade --latest --pattern "@11ty-"

  Replace "gatsby-" with the common pattern.

Configuration

Add New Syntax Languages

• See prismjs + eleventy.js file

Images

• See eleventy.js where we rock passthrough

Article Notes

These are the large yellow blocks of text in our blog-posts. We use this to bring attention to a particular detail. For example, clarifying an assumption, or giving the reader additional directions to make the article clearer.

Theare are marked up as follows:

::: note
Anything you like `in` here it _all_ works.
:::

This capability is setup in eleventy.js

Footnotes

Footnotes are great when you have additional clarifying comments or want to credit someone else work etc. For this reason, I provide a quick way of adding footnotes to your blog posts:

• Add the footnotes section

  ::: footnotes
  // your footnotes here
  :::

  You only need to do this once.

• Add your footnotes to the footnotes section

  ::: footnotes
  
  ->->-> footnote#cljs-test
  content goes here
  ->->->
  
  :::

  The cljs-test part of footnote#cljs-test becomes the html id value of the a and the li.

Additional comments:

• The above should produce an accessible footnote which includes aria-lables.
• You do not need to manually add numbers to the footnotes. This is because we have setup the CSS to dynamically count your footnotes. Having said this, you do need to put them in the correct order in the ::: footnotes section at the bottom of the file.

Updating Blog Posts

When we write blog posts a key factor in choosing topic to write about and structuring the content is ensuring I can keep the content evergreen. This choice was made after seeing so many tech blogs which are outdated months after being written. Another goal is to make it easy for readers to see what changed so when we update blog posts I like to follow some guidelines:

• The commit title should follow this pattern: Update Blog Post - Blog Post ID - Quick Summary

  Update Blog Post - 005 - Bump Deps

• Keep changes isolated and small so the diffs are easy to grok

Updating Blog Checklist

Keeping blog posts updated is important because it ensures that the work stays relevant and therefore useful to future readers. With CLJ(s) this is easier because of the stability of the ecosystem. We also take it a step further in this blog by having all the variables (versions, important resources updated on intervals etc) controlled through the site.json file.

Now, these only work for the blog, so the following subsections are noting which of the non-blog resources we need to also maintain.

ClojureScript Versions

• demo - https://github.com/athomasoriginal/demo-clojurescript-gh-pages
• video - 016 - figwheel

Atom Editor

• post - 006 - chlorine (e.g. no longer depends on Ink)
• video - https://www.youtube.com/watch?v=mEcOwtRt0f4

Blog Post Guidelines

Frontmatter

Blog Frontmatter is the stuff at the beginning of our blog-post markfown files.

author: "Thomas Mattacchione"
createdDate: '29 July 2019'
updatedDate: '05 March 2024'
date: Last Modified
layout: post
tags:
  - post
title: What the Reagent Component?!
permalink: blog/{{ title | slug }}/index.html
canonical: true
summary: "It's time to uncover the truth about Reagent components."

• createdDate: the original publication date
• updatedDate: the last modified date
  • Why both date and updatedDate? They both serve the same function and originally date was something I saw as a lower maintence way of documenting last modified. However, when I went to update the blog index to show the last modified date it became apparent that date could not be used as-is. So, instead of swapping it out and potentially creating an error, I just added updatedDate. Prefer this. We will eventually phase out the use of date.
• date: the date the post was last updated
• summary: max 140 characters tagline
• permalink: dynamically generate based on the title.
  • Some titles have special characters which don't format well or you may want the url to be different than the title. In this case you can manually write thw permalink
  • Lisp case for title is prefered because I find it more readable

Images

• Images that appear in a blog post should go in: src/images.
• Images should be prefixed with the same 3 digit code as your blog-post.
  • For example, if your blog is 001-... your image should be titled 001-image-name-0f-your-choosing.
• Example of referencing an image in a blog post

  ![screenshot of example hello clojurescript site](/001-image-hello-cljs-dev-example.png)

Links

Prefer reference links because they are reusable, allow for cleaner reading/editing of the post and when you need to update links they are all in one place. Seriously. This is a maintenance win.

Writing Style

• Less formal
  • e.g. you're instead of you are

Blog Features

This section outlines the features our blog supports. This is valuable because if you ever have to move to a different platform you have a catalogue of the required feature sets.

• HTML5 Boilerplate
• Modern CSS Reset
• Date Formatting
  • dateFilter
  • w3DateFilter
• Blog Posts
  • Heading Anchors
  • TOC
  • Created Date
  • Modified Date
  • Custom date formats
    • 20 May 2019 for created date
    • There is an off by one error if we write dates as 2019-05-19
  • Note
    • Custom markdown fence - ::: note
    • See eleventy.js
  • Code Blocks
    • Custom Syntax Highlighting
  • Footnotes
• Links open in new tab
• Global data
  • footer
  • header
  • There is a priority order for how Data is consumed by Eleventy. Familarize yourself with that. The _data/site.json is meant to contain reusable, site related global variables. Example of what this is not for: post front matter data.
• RSS feed
• Trailing slashes
• Open Graph Meta Tags
• Twitter Cards
• 404
• Sort blog posts
• Custom Signup Form
  • Behaviour: when incomplete user is directed to the hosted form screen where they can try again
• Redirects
• Generate a mailto link Simple tool to generate a mailto link so you don't have to worry about formatting.
• SVGs are inlined for performance and maximum control via css
  • move the svgs into the svg directory
  • reference in templates: {{ '/src/svg/logo.svg' | svgContents | safe }}
• Self Referencing Canonical Links
  • Built from site.url.home.link and the permalink and must set canonical: true in your blog template.
• Images
  • All images live in the images dir and we use passthrough.
  • SVGs are separate
• Custom Block - Footnotes

Before Dev

• Update _data/site.json

Before Deploy

• Add custom favicon
• Publish sitemap
• Add analytics tracking
• Update social media cards - OG, Twitter etc
• Add Apple Touch Icon
• Populate web.manifest
• Performance
  • Run through this top 10 guide - anything to improve?
  • Make images smaller
• Netlify configs
  • set yarn env variable
  • update build settings

Writing Style Guide

This is the style guide for actually writing posts.

• italic
  • New terms, extensions and filenames
  • Only the first time it appears
• inline code
  • programming terms (vars, syntax and programming tools)
• Undecided
  • This section is things I have found a need to write, but haven't aligned on anything consistent yet.
  • commands to be run/typed by users

Special Thanks

I appreciate everyone who has helped to improve this blog whenever possible. Shoutouts:

Design

• Chelsea Murray

Illustrations

• syungb

Content

• anantpaatra
• syungb
• lokeh
• skidding
• @henrikeneroth
• holyjak
• rogererens
• ludbek
• oakmac
• 3willows