S

Spegman's Every Ref.

v0.5.1

Guidelines

by Ibraheem Rodrigues

This page aims to both provide guidelines for working on this site, and in doing so establish the project's aims.

Contributing

Contributions are welcome, as long as they fit the style, aims and ethos of this project, detailed here.

If you have any suggestions or issues either submit a github issue or email me.

If you want to create content for this project, please first read over these guidelines.

You should either:

  • Fork this repo, make your changes/additions and then submit a pull request.
  • Get in touch using one of the links above

Seed README.md for how to run the jekyll site locally.

Key Terms

All pages should be written in markdown. This site uses kramdown-flavour markdown as is standard for Jekyll sites.

These are the key terms, that should be used when referring to parts of the project.

  • Spegman’s Every Ref. (aka ‘The Project’, ‘The Guide’, ‘The Site’)
    • Categories - Information groups, defined in _categories/
    • Content - Everything in the _content/ folder
      • Pages (aka ‘Guides’)
    • Infrastructure (aka ‘The Code’) - Anything that is a part of the site, but not directly viewable by the end user

Categories

Categories are defined with a markdown file in the _categories folder.

The name/path of the file will determine the url of the category index page, e.g misc.md => site.com/misc/.

Category Template

---
title: Miscellaneous # Mandatory, the name of category
description: Blah blah blah # Optional, will show up on category index page.
---

<!-- Optional content here. Will show up on category index page -->

Current Categories

Category ID Description
Miscellaneous misc Anything that does not belong in another category.
Mathematics mathematics Math(s) related reference. Geometry, Numbers, Set tTheory etc.
Science science Scientific reference - Physics, Chemistry, Biology etc.
Languages language Languages, alphabets and linguistics reference

Pages

Page files should be under their respective category in the _content folder, and must include the front matter as defined below.

Files can put in one of two places:

  1. <category_path>/<name>.md (e.g.misc/spoons.md)
  2. <category_path>/<name>/index.md (e.g. misc/spoons/index.md)

File names should separate words with underscores _ (snake case)

Page Template

---
title: Spoons # Mandatory
description: Common and popular spoons # Optional
author: j_spegman # Mandatory
category: misc # Mandatory

original: no # Optional, true/yes or false/no (default). Is this original work as opposed to a reference page?

redirect_from: # List of pages to redirect to this page from. Used when a page is moved or to link pages with similar names, e.g `/science/glass_colours` redirects from `/science/glass_colors` ([use british english](#standardisation))

image: spoon.png #  Optional, for SEO
---

Spoons come in 3 flavours...

External Site Template

If you wish to add a link to an useful external site, then do so as if you were adding a page, but use this template:

---
title: Spoons # Mandatory
description: Common and popular spoons # Optional
category: misc # Mandatory
redirect_to: https://spoons.info # Mandatory
---

A note on titles

If you have specified a title, on any page, you should not be using <h1> elements (# Title), so SEO reasons (only 1 <h1> should be on each page). There is a simple remedy - simple start immediately with <h2>/## Title elements.

Adding media

If you wish to add media to use in a page (images, etc.):

  • Use file structure 2
  • Put media files in the same folder as the page’s index.md

Media which is used in several pages in a category may be included in the category folder.

Adding a Table of Contents

To include a table of contents in on page, add the following code at the top, immediately following the front matter. This will summarise sections of your page in a tree, as denoted by titles/headers. (<h2>/## Subtitle will be a child of <h1>/## Title, etc)

---
# Blah, blah front matter
---

{% include toc.md %}

<!-- Content here -->

Writing Guidelines

Guides should be factual and to the point. However this guide is as much about interest as it is about factuality - while all included information must be true, we do not aim to be encyclopaedic.

We aim to collect things that are useful, unusual, or tell a story of the human endeavour to understand and categorise the world around us.

Standardisation

For the sake of consistency:

  • Spelling should be in British English. If words like colour/color are used in a title, be sure to redirect from the alternative spelling.
  • Use CE/BCE as opposed to AD/BC
  • Dates should be in the DD/MM/YYYY format
  • Times should be given in 24 hour format (00:00 - 23:59)

Block Quotes

To quote directly from a source, or elsewhere in the guide, use a block quote:

> To be, or not to be

When you give attribution, either link to a source as below or use the following syntax for direct attribution:

> To be, or not to be
>
> *Hamlet by William Shakespeare, Act 3 Scene 1*

> To be, or not to be
>
> [*Hamlet by William Shakespeare, Act 3 Scene 1*](http://shakespeare.mit.edu/hamlet/hamlet.3.1.html)

Maths / Chemisty

We use MathJAX to render mathematical equations. This extension handles chemistry.

Use $$ to define equations:

$$ y = mx + c $$

This works for both inline and block level (automatically detected, note $...$ is not supported by kramdown):

Quadratic equations have the form $$ y = ax^2 + bx + c $$

Quadratic equations have the form

To force it to render in the opposite level (inline to block and vice-versa) use \$$ ... $$

If $$ y = 0 $$ you can find x: \$$ x=\frac{-b\pm\sqrt{b^2-4ac}}{2a} $$

If you can find x: $$ x =\frac{-b\pm\sqrt{b^2-4ac}}{2a} $$

The LaTeX Wiki has a good reference for typesetting equations.

Citing sources and giving attribution

To cite sources or give attribution use kramdown’s footnote syntax. This supports both numbered and worded footnotes, however everything will be rendered to numbers. Prefer short descriptive words to numbers, as below

Spoons are most commonly made of steel. [^spoons_website] <!-- Link to footnote -->

Spoons come in many flavours. [^spoons_website] <!-- Use it again-->

[^spoons_website]: [https://spoons.info](https://spoons.info) (Accessed 01/04/2020) <!-- Define the footnote -->

Citation Templates

<!-- Physical reference -->
[^book]: <Surname>, <Firstname>. <Book title> <Pub date>, p<Page number>. 
<!-- Web reference -->
[^web]: [<Page URL>](<Page URL>) (Accessed <Date>) 
<!-- Media attribution -->
[^image]: [<Image owner>](<Owner or image link>) [<License type>](<License Link>) 

<!-- Examples -->
[^spoon_book]: Spooner, Daniel. Spoons of Northumbria 2004, p42.
[^spoons_website]: [https://spoons.info](https://spoons.info) (Accessed 01/04/2020)
[^spoons_image]: [Andrew Gustar](https://flic.kr/p/djVV3o) [CC BY ND 2.0](https://creativecommons.org/licenses/by-nd/2.0/)

See the kramdown footnote docs for more.

Infrastructure

Important Files

Name File Description
Home index.md Site homepage.
Guidelines guidelines.md Information related to contributing to the reference.
README README.md Information related to developing the technical side of the site.
WIP/Planned Content wip.md Record of work-in-progress or planned pages

Adding an author

To add yourself as an author, add an entry to /_data/authors.yml, like follows:

j_spegman:
    name: Jeg Spegman
    email: jeg@speg.info
    url: https://twitter.com/spegman

Your name will link to url (see top of page)

See the template for how to add an author to a page.

Versioning

We aim to follow Semantic Versioning, however as the original specification is not intended for non-code applications, the following guidelines will be used to follow semver’s spirit - chiefly to communicate intent.

Under this scheme, version numbers and the way they change convey meaning about the underlying code and what has been modified from one version to the next.

https://semver.org/

Versions should be tagged with github released on the master branch.

Content Related Versioning

Changes to the content of the site (specifically everything under /_content/) should increment the version numbers for the following reasons:

MAJOR.MINOR.PATCH

  • MAJOR - changes which overhaul content/formatting structure
  • MINOR - content additions and removals
  • PATCH - content updates and fixes (spelling, accuracy, etc.)

Important notes when changing pages (MINOR changes):

If a page is moved or merged with another, the new page should redirect from the old page url:

---
redirect_from: /misc/old_page
---

If a page is deleted, a file should be left in its place informing any users of this change.

Whether these temporary pages should be kept after a MAJOR change should be decided on a case by case basis.

Deploying to netlify

Deploys are triggered by creating a new tag on github. This will trigger a github action to build the site, and deploy it on netlify.