Zalgorithm styleguide

Notes versus posts

Notes are quick and dirty. See Writing useful notes. Posts (if they ever happen) are proper writing. Ideally, a post is the product of one or more notes.

Writing style

You’re not a machine. Don’t write like one.

Use internal links whenever appropriate. Confirm that internal links are correct prior to publishing. Keep in mind that renaming a markdown file may result in broken internal links.

Every piece of writing is either a note or a post. Notes/posts is the only hierarchy on the blog.

Writing for semantic search

Keep it in the back of your mind that the primary entry point to the blog is via semantic search. Don’t write a book under a single heading. Avoid heading sections that contain no text. At the very least, give images captions.

Notes

Spelling and grammatical errors are ok.

Notes are created in the Hugo /content/notes directory.

Posts

Spelling and grammatical errors are not OK.

Posts are created in the Hugo /content/posts directory.

Headings

The top level (H1) heading of each post is supplied by the post title during the Hugo build process. The highest level of heading that can be used within a markdown document is H2.

Keep headings meaningful. Remember that the heading hierarchy (H1 > H2 > H3, etc) for each section of writing is used in embeddings that are generated for semantic search.

Headings are used in internal links. Headings are “slugified” to generate section ids. The process of slugification replaces special characters with hyphens (-). Avoid the use of special characters (', ", ?, ...) in headings.

Taxonomy

Tags are only form of taxonomy used on the blog. Use them. Every now and then, check the tags page. Consolidate redundant tags.

References and footnotes

Refer to Zalgorithm citation style for reference and footnote syntax.

Don’t give the footnote section a heading. Footnotes are inserted automatically during the Hugo build process. (See How the Hugo build process processes footnotes.)

The reference section should consistently use the second level heading ## References. (TODO: use the “References” heading text to exclude references from semantic search embeddings.)