Design

• https://app.excalidraw.com/s/9u8crB2ZmUo/14uWaFN0z4C - Docu-thon for Catalogs with Flowershow, PortalJS and MarkdownDB - this has sketches of front page with other more general notes about purpose and approach

Content

Acceptance

• a how-to explaining the process of publishing an Obsidian vault to a GitHub repo, using GitHub desktop app

Internal video

Notes

We have a first attempt, so we know what are the pain points

https://drive.google.com/file/d/1uHWC5KuzkdcQQbra1IULmww-SNJsWpv2/view
https://drive.google.com/file/d/1j1VpRrsJcyo6N0D3d7KyflEp-7Rp-RQz/view

Covers:

• creating a new empty repository on GH
• initializing GH repo in the local folder with notes (e.g. vault)
• pushing to the remote repo

Create a first editor guide for adding and editing conten to a markdown-based site -- specifically a markdown-based, flowershow-published site and even more specifically a "MOGF" (markdown-obsidian-github-flowershow built site).

Outcome visioning 🎯 (High level acceptance)

A non-dev editor/author at Life Itself or anywhere else has a single online place to go to with (or linking to) sufficient docs to autonomously (i.e. without dev support) ...

• Edit lifeitself.org
  • Create a new blog post
  • Create a new page
  • Edit a blog post or page
• Create, share and publish a micro-catalog
  • Create locally
  • Share with others (privately)
  • Publish
• Create a digital knowledge garden i.e. content + catalogs etc

Plan of work

Prep

Content

https://coggle.it/diagram/ZG5bpZ-I6DjyVLxZ/t/editor-guide-latest-this-part-is-initial-2023-5-24-14-01

• Tutorial for each job story - first skeleton, then flesh out etc as per #929 💬2023-06-07 topic and skeleton mega coggle - https://coggle.it/diagram/ZG5bpZ-I6DjyVLxZ/t/editor-guide-latest-this-part-is-initial-2023-5-24-14-01
• datopian/datahub#936

Misc

• Reference from any other locations e.g. life itself tao, datopian playbook etc
• Deprecate any existing guides in favour of this if possible

Acceptance

TBD

Rough steps:

1. Try to locate the underlying markdown file of the page you're trying to access (e.g. through clicking on some link) to see if it exists
   2 If it's there, check the spelling
2. If it's not there, see if you can find it in another place in the repo and adjust the links accordingly
3. If this didn't help, this might be an issue in your forntend app?

Job story

As a new contributor to a Flowershow/PortalJS site (e.g. LifeItself.org), I want to edit an existing page on the website (whose contents are stored on GitHub), i.e. add/change some text, edit/add links to other pages, and/or add images to it so that the page is updated.

• What does this contributor know ...?
• Assume (but flag) you have edit access to the relevant repo/system (i.e. don't explain the process of getting the access in the tutorial)
• Any website that is markdown based with jam-stacky tendencies would be relevant here, not only Flowershow based one
• There is going to be a sandbox that readers can use when following the tutorial. A sandbox is a single instance of a simple Flowershow website with a few example pages. Assume this sandbox is already set up including automatic deployment.
• Will there be a live preview somewhere? No, not for now.
• ❗️ For now, add any terms/concepts explanations in e.g. Obsidian info callouts. They will form the basis of relevant sections in our Contributors Guide in the future.

Tasks

• Create a sandbox
  Repo: https://github.com/datopian/flowershow-sandbox; Deployment: https://flowershow-sandbox.vercel.app/
• Write a draft https://hackmd.io/qAJFi0O0Q9G4ZubeSCet9g?edit
• Write the content (no screenshots in this step yet)
• Try it out and adjust if necessary
• Improvements
  • Screenshots
  • Video (you have the script already with the tutorial)

Acceptance

• Transfer https://portaljs.org/blog/create-a-simple-catalog-of-anything-using-markdown over as a post here - source at https://github.com/datopian/portaljs/blob/main/site/content/blog/create-a-simple-catalog-of-anything-using-markdown.md ✅2024-01-03 DONE. See post here
• x-post to DataHub (at same date as portaljs) - perhaps just a sample with full link to makeitmarkdown ✅2024-01-11 https://datahub.io/blog/create-a-simple-catalog-of-anything-using-markdown
• Delete from portaljs (with redirect to makeitmarkdown) ❌2024-01-03 WONTFIX. I think we should delete only once Makeitmarkdown is complete, as backup in case anything goes wrong or we need to reference something. Added this to #20 to revisit later

Tasks

• Fix images so they show up in the migrated blog post
• x-post to DataHub blog Elisa doesn't have access to DataHub blog repository. Mohamed has published the post but still need to edit so we only have a sample with full link to makeitmarkdown ✅2024-01-11 https://datahub.io/blog/create-a-simple-catalog-of-anything-using-markdown

Which itself was migrated from markdownbased site - see datopian/datahub#994

Content to migrate is therefore likely covered in this PR datopian/datahub#996 i.e. guide page plus some howtos.

Acceptance

• Migrate content from portaljs ✅2023-12-20 DONE: see next two items:
  • Identify content ✅2023-12-20 DONE: see detailed list of items in tasks section below
  • Add the content ✅2023-12-20 DONE: see updates on items list in tasks section below
• Also check if anything left on markdownbased https://github.com/datopian/markdownbased that should move (and then close that down) ✅2023-12-19 did this in #8

Finally

• Remove from portaljs.org (and add redirect?) ❌2023-12-21 WONTFIX. I think we should delete only once Makeitmarkdown is complete, as backup in case anything goes wrong or we need to reference something. Added this to inbox of outstanding tasks to revisit later

Tasks

• Make list of things to migrate See tasks below
• Migrate content (Done this via Obsidian)
  • guide index page See flowershow
  • guide index page images (Is there a way to do this that doesn't involve manually downloading each image from GitHub and importing into Obsidian?)
  • tutorial pages See tutorial 1 and tutorial 2. Tutorials 3 and 4 have not yet been written
  • tutorial pages images
  • howtos See links to 6 howtos at the bottom of the index page

Review and recommend for integration the existing polished documentation we already have - see list below

Acceptance

• List what do we already have: url, title and summary ✅2023-10-31 see below
• What could we integrate? Make recommendations e.g. below ... ✅2023-10-31 ❌ we did not have any recommendations at the time
• Flag that info for relevant tutorials (in the issue or to team member etc) ✅2023-10-31 ❌ i think we did use some parts plus we published directly some parts

Tasks

Review each of these

• https://lifeitself.org/ecosystem/contributors-guide Title: Guide to editing Life Itself ecosystem - Summary: Detailed guide on editing the ecosystem page on Life Itself. Comprehensive with images to signpost
• https://web3.lifeitself.org/meta/editing Title: Editor's guide using Github + Obsidian/code editor - Summary: Guide on editing the Life Itself webpages, including a section for Obsidian/ other code editors
• Obsidian Tutorial meeting Recording and Transcript Title: Tutorial for editing with Obsidian - Summary: 1.5 hour video with Rufus and Nathen as well as complementary transcript
• Adding internal redirects on the website https://www.loom.com/share/ac3876bb390b417f9077a3e052986a44 Title: Video guide to adding internal redirects on the website - Summary: 2 minutes long
• link to the video that explains the Github and Obsidian workflow 💬2023-05-24 ⏭️ need access from owner (nathen)
• ➕2023-06-06 this tutorial about creating a local catalog with obsidian https://github.com/datopian/markdowndb/tree/main/examples/obsidian-dataview Title: Guide to creating catologues with Obsidian - Summary: Detailed guide with images as signposting to create catalogues, using Harry Potter characters as examples
• https://datopian.com/playbook/markdown Title: Information on Markdown - Summary: Short guide to Markdown and the basics to its usage + redirection to more in-depth tutorials

✅ DONE: Title + Summary for each resource (excluding one with restricted access)

Recommendations

Hey there! Seems there isn't any spacing on the left side when opening the site from a phone

For some phones, it makes it hard to read as the screen might curve a bit. Since the right side seems to have a border, it would be nice to have it to on the left!

Feel free to close if the design is intended though!

An inbox for keeping track of outstanding tasks that are currently paused.

Acceptance

• The following tasks have been completed (if still relevant)

Tasks

• Remove tutorial content from portaljs site and add a redirect to makeitmarkdown (see final acceptance point here)
• Remove howtos content from portaljs site and add a redirect to makeitmarkdown (see final acceptance point here)
• Transfer any images that we have decided to keep from the portaljs repo to makeitmarkdown (see comment here)
• Remove 'content' folder in makeitmarkdown repo and move its contents up a level (see Rufus' comment here) 2024-01-04 UPDATE: Have asked Ola for help on how to do this without breaking links to contents inside the folders

Inbox

Put text on the web

• How to quickly add a simple Markdown-based page
• How to edit or add Markdown-based pages locally on your computer
• How to quickly edit text on a single Markdown-based page
• How to add images to a Markdown-based page
• How to format a perfect Markdown-based page **💬 we have a basic draft but needs refinement **
• How to quickly create a sandbox website
• How to push an Obsidian vault to a GitHub repository

Publish Collections

• How to propose changes to someone else's website
• How to edit the people page
• How to debug and fix 404 errors
• How to hide a Markdown-based page without removing it from the content folder
• How to add a signup form
• How to theme the website
• How to redirect pages
• How to add tables, charts, or maps
• How to create and use custom React components in Markdown pages?

From specific people

Nathen https://github.com/orgs/life-itself/discussions/393#discussioncomment-5460864

How to correct a pull request

One thing I keep getting stuck on is how to not include changes into a pull request and to remove those changes as if they didn't happen. For now I just commit and then do the fixes, but this seems inefficient.

Other questions

• How to make two different pulls requests
• How do we symlink pages. And what is symlinking?
• How to update the teams page
• How to use components 💬2023-05-24 relevant for using components provided by that platform
  • How to create and use bespoke components? ✅2023-05-24 ❌ not so relevant as we don't support bespoke components so much
• How to use tailwind
• How to use css
• How to redirect pages

Zaib https://github.com/orgs/life-itself/discussions/393#discussioncomment-5502358

I have learned how to use Obsidian from Nathen, he showed me how to use it and we recorded the video. I followed the video later to create the project pages and people page. The problems I encountered are:

• A clear understanding of the flow of Syncing the Fork, Pull origin, and push origin and creating the pull requests.
• How to add images from Vault
• How to add internal and external links
• how to edit the people page
• The protocols around making edits in Obsidian, for instance, I had to delete the image from the vault when I removed it from one of the pages, I didn't know this from the start.
• Lastly, the protocol around updating the Issues in the "current iteration" in Backlog All.
• On-going Problem: How to fix merge conflicts

I have a clear understanding of these right now, but in the start it was confusing. A walk-through guide in navigating GitHub and Obsidian would be very helpful for people just getting started.

Rufus https://github.com/orgs/life-itself/discussions/393#discussioncomment-5461119

• How to use excalidraw and specifically auto embed the svgs (cf https://github.com/life-itself/diginomics/blob/main/content/notes/combining-pieces.md)
• Why svg over png (if you have a choice)
• Storing image files locally?

From Lauren - Aug 2023

Useful How to's for newer members of the team, or less frequently completed actions

• Add a page with a Hero + Content layout
• How to open new repositories on Obsidian / general How to of where to go for what overview
• How to sync Obsidian so that it represents the actual Github repo
• How to delete old branches
• How to complete a review when you are assigned as a reviewer
• How to add and link an image into a page/post (for example I had an issue with the tenzo 9 blog and the main image showing up on the page) (Lauren to create issue)
• Templates specific to LI section for main pages/posts/layout
• How to find the link to an image in the asset list (if you know the name) so you can drag it into a blog

Create a set of materials explaining a markdown-based approach to building websites, taking notes and more. i.e. why and how to use markdown to publish websites, make wikis, create lightweight "databases" and more. "Why markdown-based approach is an awesome alternative to notion and things like that ..."

Inspiration (in a different area): https://web.archive.org/web/20200421114352/https://nextjs.org/learn/basics/create-nextjs-app

Immediate goals

• #7 ✅ 2023-12-20 DONE. Content migrated to makeitmardown
• Split into sub-pages that link (a la nextjs example) and have table of contents on front page ✅ 2024-01-15 see [here] for first page of tutorial series (https://makeitmarkdown.flowershow.app/learn/introduction)
• "inbox" either issue or page where you dump links of stuff to process and excerpt any useful parts

Acceptance

• Sketch the outline ✅ 2024-01-05 see skeleton.md file in repo. Also see top right of https://coggle.it/diagram/ZG5bpZ-I6DjyVLxZ/t/editor-guide-latest-this-part-is-initial-2023-5-24-14-01
• Check existing materials we can use ✅ 2024-01-05 content from PortalJS guide is largely re-usable
• Write primary tutorial 🚧 2024-01-08 in progress. Tutorial 1 and Tutorial 2 ready, tutorials 3 and 4 in outline form (Elisa doesn't have the technical knowledge to do tutorial 4)

Tasks

• Write-up nextjs example as a great thing to learn from See below under 'Notes'. Have done up to Lesson 3 as this feels like enough to understand the logic.
• Write tutorial(s)
  • Skeleton See skeleton.md file in repo
  • Flesh out 🚧 2024-01-15 in progress. Tutorial 1 and Tutorial 2 ready, tutorials 3 and 4 in outline form
  • Review
  • Finalize
• Move everything at the /learn/ page (and subpages of this) (so introduction moves to /learn/ and everything becomes subpages of that ...)
• Make a "readable" table of contents on the /learn/ page using headings that are sentences (so it is readable) ✅ 2024-01-15 see here - Rufus to review
• Look at the coggle and consider moving key parts of it to a canvas ...
• Get 2-3 volunteers to read through and feed back
  • Volunteers recruited Volunteers recrtuited: Alex (Bergerac Hub), Lauren, Simon Grant
  • Shared link Lauren and Simon have the link
  • Received and processed feedback Received Lauren's feedback
  • Incorporated feedback
• Incorporate link to / content of contributor's guide for adding to Life Itself ecosystem site (see issue 144 in ecosystem repo)?

Sketch of full Learn tutorial

Rufus wrote on 23-12-19:

• Intro
  • Why markdown-based? (websites etc)
  • What this tutorial/course will do
  • What you'll have at the end
• Basics
  • What is markdown!
  • What do we mean markdown-based (in more detail)
• Let's start
  • ❓ do we start locally or on github? we are focused on website so let's do github first ...
  • ...

Notes

NextJS example

• Lesson 1: Create a Next.js App
  • Page 1 (Introduction to what NextJS is and why useful)
    • The problem
    • Next.js: The React Framework
    • About This Tutorial
  • Page 2
    • Setup
    • Create a Next.js app
    • Run the development server
  • Page 3
    • Welcome to Next.js - shows the result!
  • Page 4
    • Editing the page
    • Next Up: Creating Pages
• Lesson 2: Navigate between pages
  • Page 1
    • Recap context
    • What You’ll Learn in This Lesson
  • Page 2
    • Setup
  • Page 3
    • Pages in Next.js
    • Create a New Page
  • Page 4
    • Link Component
    • Using <Link>
  • Page 5
    • Client-Side Navigation
    • Code splitting and prefetching
    • Summary
• Lesson 3: Assets, Metadata, and CSS
  • Page 1
    • Recap context
    • What You’ll Learn in This Lesson
  • Page 2
    • Download Starter Code (Optional)
  • Page 3
    • Assets
  • Page 4
    • Metadata
    • Adding Head to first-post.js
  • Page 5
    • CSS Styling
    • Writing and Importing CSS
  • Page 6
    • Layout Component
    • Adding CSS
    • Automatically Generates Unique Class Names
  • Page 7
    • Global Styles
    • Restart the Development Server
    • Adding Global CSS
  • Page 8
    • Polishing Layout
    • Download Your Profile Picture
    • Update components/layout.module.css
    • Create styles/utils.module.css
    • Update components/layout.js
    • Update pages/index.js
  • Page 9
    • Styling Tips
    • Using classnames library to toggle classes
    • Customizing PostCSS Config
    • Using Sass

Meetings

2024-01-10 Rufus & Elisa sync

Otter transciption
[Google Meet recording](avg-nsou-cwj (2024-01-09 17:36 GMT+1))

Update

• Have added .md files (that link) for each of intro, motivation, and tutorials 1-4 on repo.
• Intro/landing page complete (though may be subject to revisions depending on content of the next page) (https://github.com/datopian/makeitmarkdown/blob/main/introduction.md)
• 80% complete on writing out the 'motivation'/what is markdown page (haven't pushed the changes to motivation page to GitHub yet)
  • Currently working out how to make the 'why use markdown' specific to websites (rather than generic advantages of Markdown, which is what we had on the skeleton)
• Have recruited 1 volunteer so far 👏👏

Questions

• Is it okay to reuse most of the material that Ola wrote? Yes
• Tutorial 4 is not written and I don't know how to do it... Put a note saying under construction...

Rufus comments

(Note: moved these under 'tasks' above)

• Move everything at the /learn/ page (and subpages of this) (so introduction moves to /learn/ and everything becomes subpages of that ...)
• Let's check the skeleton again together
• Make a "readable" table of contents on the /learn/ page using headings that are sentences (so it is readable)
• Look at the coggle and consider moving key parts of it to a canvas ...

Skeleton

• Make It Markdown does X
• Markdown is a lightweight markup language used to format text
  • TODO: break this down + give examples
    • Markdown is a way to author that contrasts with with WYSIWYG editors like Word we are used to by presenting
  • Yet Markdown uses formatting that aims to be close to what we would expect so the raw marked up text is still human readable TODO: shorten
    • The markdown name comes frm the contrast to markup
• Markdown is great because it is X, Y, Z
  • Simple and intuitive
  • Portable and compatible
  • Flexible and extensible
  • Platform-independent
• ...

Acceptance

• All issues on markdownbased are processed (migrated or deleted etc) ✅2023-12-14 migrated or consolidated into #2
• Migrate all content ❌2023-12-14 all relevant content is on portaljs site and is therefore part of #7

Notes

• https://github.com/datopian/markdownbased/issues/4 - github basics ✅2023-12-14 migrated content and remove issue
• ... many more

List as of 2023-12-14

Job stories for editor guide(s) (what 'How to...?' questions are wanting to be answered?)

Personas

Who are we writing for?

We are writing for non-technical people i.e. not developers. That said, in most tutorials we are assuming ...

• A basic knowledge of markdown
• Already using github

Later we will add support for learning these too.

If writing for devs we will flag that

If we are writing for a developer/technical editor we will flag that and say e.g. "dev editor" or something like that ...

Personas List

Our personas and their skill levels.

• markdown (levels)
  • 0: you don't know what markdown is
  • 1: you know what markdown is and have seen it but aren't familiar
  • 2: ...
  • 3: you are familar with markdown formatting. You could use a markdown editor and know where markdown would be used.
• markdown plus: you know markdown plus the advanced features like footnotes and tables, code blocks etc
• git(hub):
  • 0: you don't know what git or github are
  • 1 You know what it is, the different functionality it can provide and why it is used, and (some of) the associated programs that can be used with it
  • 2 ...
  • 3
• wordpress: editing previous knowledge related to the backend of programs for visual layout and confidence in navigation i.e. wordpress
• obsidian: none
• hackmd: none?
• any coding/scripting (used in Brevo) (Javascript?): none
• JAMStack: you are familiar with with JAMStack (Javascript + API + Markdown) websites including their construction and deployment. i.e. you are a dev with at least enough knowledge to build and deploy such a site and probably with some javascript knowledge.

Job Story

When writing documentation and guide for editing markdown + Flowershow/PortalJS based sites I want job stories so that I know what to prioritize to write and what i should be addressing

Acceptance

• Personas identified
• List of job stories
• Categorize job stories in some useful way
• Prioritized job stories

Tasks

• Create personas or at least identify skill level we are aiming at
• Collect existing needs and job stories
• Brainstorm high level categories

Job Stories

4 high level jobs / journeys

• Website: put content on the web. Create a markdown-based website, update it, add collaborators and discover markdown superpowers 🚀🦸‍♀
• Collections: create and publish collections of things: Create markdown-based "database/catalogs", collaborate on it and publish it ...
• Data: Publish data or data stories. Create markdown-based data catalog/portal/data-rich content, update it and publish it
• Garden: make a knowledge garden. create a markdown-based wiki / knowledge garden with linked notes and more.

And a combo one: (very common actually)

• Publish a site integrating content, collections, data and a garden I want to build a site combining some or all of these features!

And a sixth "meta" story:

• Why FOGM? i.e. why use FOGM rather than e.g. wordpress to address these jobs?

Sharing and Publishing: distinct functionality relevant to each high level job story

For each of the above you have a spectrum of potential sharing that relates to "where" you are doing this:

• Personal: you are just creating for yourself e.g. locally on your machine
• Shared: you want to be able to share the result
• Published: published on the web, for everyone to access

A common user journey goes from personal/local first to sharing to publishing on the web.

graph LR

local[Make local note]
local --> addmore[Add more notes]
addmore --> share[Share with others]
addmore --> publish
share --> publish[Publish as website]

Put text on the web

• I want to put a landing page on the web
  • What is a landing page?
  • Hero
  • Call to action
  • Signup etc
• I want to put up a note / post / article / report
  • Long-form text
  • Author
  • Date
  • ...
• I want to create a blog: essentially article plus one very specific version of "collection of stuff"

Publish Collections

• I want to publish a collection or catalog of stuff: on its own or embedded elsewhere e.g. a portfolio, a data catalog, my favorite movies, a list of books, a list of people ...
  • List of items
  • A browse/search page
  • NB: these can grow more complex e.g. multiple lists of items which connect e.g. organizations and the topics they work on

Publish Data

TODO

Knowledge garden

• I want to create a knowledge garden/wiki: i.e. docs are interlinked

Why use this approach (POGM)?

TODO: still needs refactoring ...

There are lots of ways to address these different needs from classic CMS and blog platforms like wordpress to wikis etc.

However, few of them use markdown (so why use markdown)

Our contention is that a markdown-based approach using PortalJS/Flowershow/Markdown integrated toolkit is really great because ...

• Many fewer once you add markdown requirement.
• And we are offering one specific set of tooling to do this.

❗️ List of howtos to be written

Put text on the web

• How to quickly add a simple Markdown-based page
• How to edit or add Markdown-based pages locally on your computer
• How to quickly edit text on a single Markdown-based page
• How to add images to a Markdown-based page
• How to format a perfect Markdown-based page **💬 we have a basic draft but needs refinement **
• How to quickly create a sandbox website
• How to debug and fix 404 errors
• How to hide a Markdown-based page without removing it from the content folder
• How to add a signup form
• How to theme the website
• How to redirect pages
• How to add tables, charts, or maps
• How to create and use custom React components in Markdown pages?

Knowledge garden

• How to push an Obsidian vault to a GitHub repository

Publish Collections

• (Tutorial) Create a catalog of anything using Markdown files in Obsidian

Collaboration

• How to propose changes to someone else's website

⬇️ LifeItself-specific

• How to add or edit the content on the Life Itself ecosystem page
• How to edit the people page
• How to edit the teams' page

Notes

Nathen https://github.com/orgs/life-itself/discussions/393#discussioncomment-5460864

How to correct a pull request

One thing I keep getting stuck on is how to not include changes into a pull request and to remove those changes as if they didn't happen. For now I just commit and then do the fixes, but this seems inefficient.

Other questions

• How to make two different pulls requests
• How do we symlink pages. And what is symlinking?
• How to update the teams page
• How to use components 💬2023-05-24 relevant for using components provided by that platform
  • How to create and use bespoke components? ✅2023-05-24 ❌ not so relevant as we don't support bespoke components so much
• How to use tailwind
• How to use css
• How to redirect pages

Zaib https://github.com/orgs/life-itself/discussions/393#discussioncomment-5502358

I have learned how to use Obsidian from Nathen, he showed me how to use it and we recorded the video. I followed the video later to create the project pages and people page. The problems I encountered are:

• A clear understanding of the flow of Syncing the Fork, Pull origin, and push origin and creating the pull requests.
• How to add images from Vault
• How to add internal and external links
• how to edit the people page
• The protocols around making edits in Obsidian, for instance, I had to delete the image from the vault when I removed it from one of the pages, I didn't know this from the start.
• Lastly, the protocol around updating the Issues in the "current iteration" in Backlog All.
• On-going Problem: How to fix merge conflicts

I have a clear understanding of these right now, but in the start it was confusing. A walk-through guide in navigating GitHub and Obsidian would be very helpful for people just getting started.

Rufus https://github.com/orgs/life-itself/discussions/393#discussioncomment-5461119

• How to use excalidraw and specifically auto embed the svgs (cf https://github.com/life-itself/diginomics/blob/main/content/notes/combining-pieces.md)
• Why svg over png (if you have a choice)
• Storing image files locally?