The garden manual

A page in which I outline the rules by which I run the garden. I think of this as my reference, what I come back to when I have to remember how this all works.

The principal component is a node

Each page in the garden is a node - one piece of information, or perhaps a bunch of small pieces stuck together. Ideally when a node gets big enough you can split it into two or more.

I’m drawing from Wikipedia a bit here - each node should basically be a Wikipedia-style “article”, with the ability for that to be a bit of a stub rather than something fully fleshed-out right away.

Each node is a url

Each node has one URL which doesn’t change, even if you shift the page around in the heirarchy. A node’s url might change if its title changes, but putting it into folders etc. does nothing to alter its path. This is important to ensure links between nodes remain even across restructures.

A node is any .haml, .md, or .erb file in the /g/ directory.

Folders are for author-directed grouping

I can use folders on my end to organise these pages, but they don’t have any bearing on the final layout of the garden.

(In reality I may ditch folders as too complex, especially when I start to figure how assets work.)

Garden nodes are organised by tag

If I want to group nodes, I can give them a tag, and that lets us group them together.

We aid organisation through helpers

Helper functions allow me to build, for example, tag summary boxes, tables of contents, etc. Helpers are basically functions in the static site generator itself.

Markup

You can mark up a link using double-brackets ie [[Something]]. This will then display the text Something and link to the garden page something/. Of note:

• Assumed all garden page URLs are lower case
• Special characters and spaces replaced with underscores when converting from title to URL.
• No more than one underscore in a row, no leading or trailing underscore, for URLs

So for example, Boondoggles? will have the URL boondoggles.

You can always specify eg [[link_here|Some Text]], which will display Some Text but will link to the garden page link_here.