This is the source for https://mtlynch.io/.
New code should adhere to the appropriate Google Style guide for the given language:
script/_serve_dev.sh builds the site in dev mode and starts a web server on http://localhost:4000.
.travis.yml builds the site in production mode and pushes the static files to Firebase.
Dev and prod configurations should be as similar as possible. Any change in dev should also be made to prod and vice versa, except for features we deliberately make different for dev and prod (e.g. removing GA tag from dev, removing jekyll-admin from prod).
This blog uses the Minimal Mistakes theme.
Where possible, avoid duplicating code from the theme. Sometimes this will be unavoidable. The blog currently duplicates theme code in several places, but we seek to minimize this duplication.
If a PR has merge conflicts with the main repo's master branch, rebase the PR onto master. Do not include merge commits in a PR.
PRs should have a descriptive one-line summary to explain the change. The PR description should add any additional required context or explanation for the change. For simple or obvious PRs, a PR description is not required.
If the PR fixes an issue, include the text "Fixes #XX" in the PR description, where XX is the repo issue number. This allows Github to cross-reference between PRs and issues.
If HTMLProofer fails on a broken link, we have three options: suppress the error, fix the link, or remove the link.
You should suppress the error if the link works fine in a browser, but fails in Travis occasionally. To do this, open _tests/build, update the --url-ignore flag for the htmlproofer command. Add a comment above the command to explain why we're adding this suppression. Be especially conservative about suppressing warnings on affiliate links (links to products that can be purchased) because we care when these die.
If the link is just permanently broken and does not load, even in a browser, either replace the link with another that achieves the same effect or remove the link entirely.
- Headings start with
<h1>(single hash in Markdown). - Headings use sentence-style capitalization (only first word is capitalized).
- Headings do not have trailing punctuation.
- Author is first-person singular (I).
- Reader is second-person singular (you).
- Readers of the blog are collectively referred ot as "readers" or "visitors."
- Readers are not referred to as "users" and should never be described as "traffic."
- For 1-9, spell out the number.
- Except: When the number is a multiplier (2x, 9x).
- For all other numbers, use numerals.
- For numbers 1,000 or over, write commas to separate thousands.
- For number ranges, use a regular hyphen and no space (200-300).
- Use AM/PM, separated by a space (2 AM, 4:30 PM).
- When referring to non-specific people (e.g. "the user", "the client"), use "they."
- reddit is written all lowercase.
- Put e.g. or i.e. within parentheses (e.g. like this).
- Always use an Oxford comma.
- ebook (not e-book)
- Place the file into the
_filesdirectory. - Add yaml frontmatter to the file with a title key, for example:
--- title: "filename.extension" ---
- In the post, use the below syntax to include the code sample.
The
{% include files.html title="filename.extension" language="bash" %}titleparam is required and needs to match the title key that was inserted in step 2. Thelanguageparam is optional and indicates the syntax highlighting language to use for the file.
- Place the yml file into the
_ymlsdirectory with no file extension. - Add yaml frontmatter to the file with a title key, for example:
--- title: "filename.yml" ---
- In the post, use the below syntax to include the yml file.
The
{% include files.html title="filename.yml" language="yml" %}titleparam is required and needs to match the title key that was inserted in step 2. Thelanguageparam is also required and must be set to "yml".