[epic] Primary tutorial that walks through creating a markdown-based website with markdown-based MOGF approach

[rufuspollock]

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

• Migrate content from portaljs.org/guide to this site #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
• ...

[elisapaka]

@rufuspollock I've tidied up this issue and added a skeleton for the website. Let me know what you think about the skeleton, so I can start fleshing it out.

[rufuspollock]

@elisapaka not quite sure what part is skeleton. Part we started as Skelton seems unchanged. Can we update that part.

[elisapaka]

@rufuspollock It's under 'Sketch of full site'. I didn't want to delete what you had written in case we wanted it as reference, so I left it at the bottom of the issue and annotated as "Rufus wrote on 23-12-19". The skeleton is still very basic, but I wanted to make sure I was on the right track before making further on it.

[rufuspollock]

@elisapaka ok - in that case i think there is a confusion.

Can we focus on the tutorial and the skeleton should be readable as it is ... e.g. this isn't very clear

 - What markdown is and what it's for
 - Why a markdown-based approach is better than alternatives
 - The MOGF approach

This is better ...

 - Markdown is a way of adding markup to plain text e.g. `**xxx**` to indicate bold
 - Markdown is for XXX
 - Markdown-based approach has these distinctive features: the format is open and simple and usable anywhere (need probably to explain why most text formats like google docs word etc arent'), it is highly extendable etc
 - We are going to set out an approach to working with markdown that we term "MOGF" for markdown + obsidian + git(hub) + flowershow. This combination or "stack" of tools is free and easy to use ...
 - Why now for markdown? Because previously markdown was a bit "geeky". However, improvements in tooling make it attractive etc etc. TODO: Give analogy from another area ...

i'd suggest getting one initial part of the skeleton fleshed out and i can review and then go from there ...

Finally, note we already have the first part of this sketched out for you in the form of the existing tutorials which should form part of an overall "learn" sequence ("learn" as in the nextjs.org/learn mega-tutorial)

Focus on tutorial

I think the skeleton (and this issue) is about the main tutorial - rather than the whole site (which is what you have atm).

[rufuspollock]

@elisapaka i also wouldn't bother repeating the task list until we have the skeleton sorted (and even then repeating the same 4 actions for each section isn't so useful IMO as it creates a lot of noise for now)

[rufuspollock]

@elisapaka and Rufus talked about this yesterday and conclusion was to start with a rough outline of the first sections.

[elisapaka]

@rufuspollock I've written the skeleton for the main tutorial series. It's currently saved as a note in my Obsidian locally, and I'm wondering what the best way to share it would be?

I can copy it into a google doc, but the formatting will be lost; or I can put it into an issue (either this one, or create a new one), but it's rather long and it might look a bit messy and be inconvenient to edit and comment on. Are there any other ways of sharing I haven't thought of?

UPDATE: Following Lauren's suggestion, I've created a skeleton.md file in the repo (link) and added you as reviewer when I merged the pull request. Some notes:

• I think it works best to talk about what Markdown is and why we use it on the homepage (+ an overview of the MOGF approach), and then have a 'Start now' button that takes you to the first of a series of tutorials.
• Following inspiration from Next.js, my suggestion is to break down each tutorial into a set of pages that interlink (6-7 on average) - this is what the numbers correspond to in the skeleton.
• Most of the structure for the tutorials I've copied over from Ola's posts on the PortalJS site. In tutorial 1, I've removed mentions to Vercel and added instructions for Flowershow.
• Tutorials 1-3 I'd feel confident enough to edit or write in full (or at least give it a try!) Tutorial 4 covers things I don't have any experience with, so I'd have to learn how to do them first if I were to write it myself.

[rufuspollock]

UPDATE: Following Lauren's suggestion, I've created a skeleton.md file in the repo (link) and added you as reviewer when I merged the pull request. Some notes:

I've left an overall comment. Overall you are doing great. I just think the skeleton has got a bit more detailed than a skeleton and at least for me reviewing the overall direction a simpler skeleton (perhaps extracted at the top) would help.

Following inspiration from Next.js, my suggestion is to break down each tutorial into a set of pages that interlink (6-7 on average) - this is what the numbers correspond to in the skeleton.

Small comment: this splitting into individual small pages is something to do last and is easy to do and kind of arbitrary - as i mentioned when doing the overview of nextjs i would even remove the "page X" sections and just consolidate (roughly they split every couple of substeps so obvious how to re-add).

I wouldn't include this division for now in the skeleton as it adds noise - it is just something for the UI when we actually make the site (and could come later frankly)

[elisapaka]

@rufuspollock I've added a readable ToC on the introduction page at /learn. See here.

I opted for including all subsections, but if you think it's more noise than helpful I can delete them (I mean the ones not hyperlinked). I tried to do wiki-links to specific sections in Obsidian, but it doesn't seem to be rendering in Flowershow and I don't have the time right now to investigate...

Tutorial 1 and Tutorial 2 are all done, while tutorials 3 and 4 are in outline form. Tutorial 3 I could write out in full, but this week I'm working on cohere+ stuff. Tutorial 4 I don't have the technical knowledge to actually write myself.

Let me know if you have any feedback. I haven't yet shared this with Alex who volunteered to go through it and leave feedback, as it makes more sense to me to wait until tutorial 3 is also done. But if you think otherwise I can share.

[rufuspollock]

@elisapaka this is excellent work 👏

I think you can go ahead and finish tutorial 3 and then share it with your colleage.

Could you also sync with @olayway about getting the site for this located at makeitmarkdown.com (this is registered in datopian cloudflare domains) (NB: this should probably be a separate issue of its own).