Somewhere on each post page there's a list of linked posts.

I think we can just group forward and backlinks together. I'm unconvinced there's much value in differentiating them.

But maybe to play it safe we should have some metadata on the links that says whether it's a front or backlink and then we could distinguish them with icons or something else subtle.

https://starlight.astro.build/

• There are posts
• There is an index page of all posts
• You can click on posts and view them
• Posts have metadata and it's rendered to the page

Likely Inter 4.0 as part of the free option. Pick a nice serif to pair it with.

Commercial Type for fancy options.

Maybe Blanco by Foster Type

Why are we building this?

• To solve our own problems. Our existing gardens built in Next.js are absurdly complex for what they need to do, and lead to bugs and confusion (e.g. animation issues with SSR, build errors). Want to turn them into simpler sites with less JavaScript and overhead.
• To give developers a strong base layer to build their own gardens off
• To give web-development-curious people a reasonably simple tool to build their own gardens with (if they're willing to learn some basic web development)

What does this have that we don't think other solutions do?

• Backlinks
• Version control
• Exploratory information architecture
• RSS publishing control
• Micro and macro post sizes
• Distinct post types
• Ownership and control (not publishing on proprietary social media platforms)
• Syndication to existing social media platforms

Why does it need to exist in the world?

• To solve our own problems:
  • Rebuild our gardens in a simpler way that will allow us to publish more and spend less time squashing arbitrary bugs
  • Set our gardens up for longevity; build them primarily in plain HTML/CSS/JS, rather than React, Vue, etc.
  • Set up a system that enables us to publish more across a range of content types
• To make it easier for people to build their own digital garden without making everything themselves. Give people an opinionated tool that does the heavy lifting for them
• To show people how a gardening approach changes the way you can write and publish to the web
• Help get more people to own their own website outside of proprietary social media platforms

What's the guiding philosophy here?

• Simple DX
• Easy to write new content
• Content can and should evolve over time
• Focused on evergreen content rather than chronological updates
• Beautiful, readable typography

Target Audience and Required Knowledge

Web developers
People willing to learn a little web development

Need to know how to use the command line, Github, and a code editor like VS Code

What's absolutely essential – you couldn't use Arbour without it?

What can we save for future versions?

Break core features down into which ones we should implement first, second, etc.

The vibes are very important

Natural, neutral, greens, browns, woody stuff, warm beige lights. Some brighter green/yellow accents.

Subtle dynamic elements would be great. Like slightly shifting hues based on the reader's current time. Slow gradient animations. Give the space a bit of life.

Make a mood board.

Resistant to having light/dark mode shift.
Maybe users can pick one or the other, but continuous background shifts fuck with image displays and contrast (unless I decide I reallllly want to do the dynamic colour shift from day > night).

Have at least 2-3 colour vibe schemes to pick from

Somewhere in the repo there's a place we can declare and edit all the post types and their properties.

Draft schemas (may change - good assumed starting point)

Post
(Generic type that covers what I call both "notes" and "essays" – only diff is length and done-ness. This is the base type for more specific post types)

• Title
• Description?
• Cover image?
• Start date
• Updated date?
• Growth stage
• Assumed audience?
• Confidence?
• Importance?
• Tags/topics (these are thematic: "biochemistry", "javascript", "interface design")
• (Content)
• (Backlinks)

Book

• Title
• Author
• Cover
• External link?

Micropost

• (Content)
• (Backlinks)

Question

• (Content)
• (Backlinks)

Belief/Claim/Zettle

• (Content)
• (Backlinks)

Maybe these are implicit as part of the folder structure and metadata within files or maybe it's explicit somewhere like types.json?

Assuming we should keep these super simple, but in theory (technically savvy) users should be able to build other custom types with unique properties in the system, such as:

• conference talk
• podcast episode
• lesson plan
• code snippet
• sketch
• molecule (maybe I'm a biochemist IDK)
• case study
• project
• design pattern
• film
• data visualisation

Final Spec: Specs/VersionControl.md

Concept

Macro content on the garden can have new versions added to it.

Versions are not created automatically every time you edit a post. Authors need to explicitly decide a piece has changed enough to warrant a new version.

Older versions should still be preserved, and any links to them should still work.

Each piece of content still needs to have a canonical link. E.g. bob.com/quantum-physics
This link should ideally always go to the latest version. If it links to a previous version, there should be a clearly visible banner / element on the page that says this is an old version, and links people to the latest version.

Use redirects to always sends users to the latest version. We can forward people from the canonical link to the latest. E.g. bob.com/quantum-physics -> bob.com/quantum-physics/v2 or bob.com/quantum-physics/v3

We expect most posts won't have version. Posts without versions simply live on their canonical URLs.
Once a post has two versions, we add v1 and v2 to the end of the URL

So bob.com/quantum-physics becomes bob.com/quantum-physics/v1 and bob.com/quantum-physics/v2
The canonical URL now forwards people to the latest version.
This decision is based on the assumption authors usually want people to read the latest version.
Readers can still view and directly link to v1, but the default URL redirects to v2

Requirements

Authors must be able to:

• Create new versions of content
• Keep old versions without worrying about losing them
• Link to both old and new versions

Readers must be able to:

• View previous versions of content
• Know what version they're currently looking at
• Easily navigate to previous versions via a version sidebar or similar
• (??) See a diff of what's changed between the two versions

Explore designs for a single macro post (longform)

• Metadata displays
  • Linked posts
  • Version history
  • Growth stage
  • Type
  • Title
  • Dates
  • Description?
  • Cover image?
• Content layout
• Common components

https://github.com/MaggieAppleton/arbour/blob/main/Specs/Prototype.md

Some initial exploration in Figma of navigation patterns for:

• index pages
• navigating to other posts from a single post

• Decide on how we're doing image optimisation
• Implement image optimisation
• Draft up docs explaining how image optimisation works

https://github.com/MaggieAppleton/arbour/blob/main/Specs/Backlinks.md

https://github.com/MaggieAppleton/arbour/blob/main/Specs/MicroMacro.md

What does it look like to view a single micro post?
What do micro posts look like as collections?
How do micro posts look when embedded in macro posts?
What actions and metadata are visible on a micro post?
How do you create a new micro post? What's the authoring experience like?
What metadata makes sense on micro posts?