How to use a MarkdownDB to build simple catalogs of stuff (and why)

[rufuspollock]

This is about wow we could use a MarkdownDB to build, for example, a gallery of the portal examples. Generally, its about why markdowndb is super cool for building small catalogs of stuff: whether that stuff is portals, recipes, harry potter characters or whatever.

How would we do this? Let's walk through the ways we'd do this starting with the simplest approach and iterating. Ultimately we'll see why markdowndb approach is attractive.

Summary:

Two basic options

• Dump into a single text file (e.g. markdown or even gdocs)
  • 👍 very quick to start. natural for dumping free text, excerpts, images etc. metadata as bullet lists etc
  • 👎 no individual pages (just an index page)
  • 👎 painful as file gets large
  • 👎 if i want to present in some useful way have to manually reorder the file (and can't reorder by different items)
  • 👎 can't expand to have e.g. tags/topics and list by these
  • 🛑 no way to filter or query or even extract individual items later
  • ⏭️ Put in individual text files
    • 🛑 solves scale problem and presentation to some degree (can have pages ofr individual items) but no index page
• Open a spreadsheet (google sheet, airtable, notion etc)
  • 👍 structured, nice overview at a glance
  • 👎 Mostly proprietary, content is in the cloud i don't control
  • 👎 👎 unstructured content is really painful (markdown in a table cell), images are kind of sucky
  • 👎 publication requires a bit of work
  • ⏭️ move to markdown with structured metadata = MarkdownDB :db

Fundamental choices

• Unstructured: text files
• Structured
• Want the best of both world! Structured and unstructured material in same place

Needs

• Put in structured data (e.g. start and end dates) and unstructured content (e.g. text notes)
• Easily add images (e.g. just copy and paste)
• Create index pages that list all items
  • Create super-powered index pages with filtering and searching
  • Overview of a lot of items at a glance (e.g. table like)
  • Easily see the main attributes
• individual pages for each item with a nice layout
• 🏆 turn unstructured content into structured content e.g. extract title or main image as attribute for use in eg. index pages
• 🏆 Moderated contribution workflow
• 🏆 Real-time collaboration

Dump in a text file

Boot a markdown file e.g. README.md and start pasting info

## Example XX

- 🔗 https://...

Screenshot

Some free text about it ...


## Example YY ...


- ...

At some point we are like ... hmmm ... I want to be able to search this list or make it look nicer e.g. with html "cards"

⏭️ Ok, so i need to split these out to individual files (or move to airtable / spreadsheet etc)

v2

/README.md
/portals/
  example-1.md
  example-2.md
  ...

where each file is like

---
url: ...
title: ...??
start: ...
end: ...
---

# Example XX

Screenshot ...

Some free text about it ...

🚩 I call this a "markdowndb" ... each file is basically an entry in a table ...

Have built a library for working with markdowndb ...

https://github.com/flowershow/flowershow/tree/main/packages/markdowndb

Notes:

• why not airtable, google sheets etc
  • Because you want free, rich text and that sucks
• If you are sophisticated enough to use git(hub) it will integrate with deployment later