[core][s]: darkmode storybook addon

Tutorial 4 (overview): Customising your website locally and previewing your changes locally

nx.json

@@ -5,7 +5,13 @@
     "default": {
       "runner": "nx/tasks-runners/default",
       "options": {
-        "cacheableOperations": ["build", "lint", "test", "e2e"]
+        "cacheableOperations": [
+          "build",
+          "lint",
+          "test",
+          "e2e",
+          "build-storybook"
+        ]
       }
     }
   },
@@ -30,6 +36,14 @@
         "{workspaceRoot}/.eslintrc.json",
         "{workspaceRoot}/.eslintignore"
       ]
+    },
+    "build-storybook": {
+      "inputs": [
+        "default",
+        "^production",
+        "{projectRoot}/.storybook/**/*",
+        "{projectRoot}/tsconfig.storybook.json"
+      ]
     }
   },
   "namedInputs": {
@@ -39,7 +53,10 @@
       "!{projectRoot}/**/?(*.)+(spec|test).[jt]s?(x)?(.snap)",
       "!{projectRoot}/tsconfig.spec.json",
       "!{projectRoot}/jest.config.[jt]s",
-      "!{projectRoot}/.eslintrc.json"
+      "!{projectRoot}/.eslintrc.json",
+      "!{projectRoot}/**/*.stories.@(js|jsx|ts|tsx|mdx)",
+      "!{projectRoot}/.storybook/**/*",
+      "!{projectRoot}/tsconfig.storybook.json"
     ],
     "sharedGlobals": ["{workspaceRoot}/babel.config.json"]
   },

package.json

@@ -20,10 +20,20 @@
     "@nrwl/js": "15.9.2",
     "@nrwl/linter": "15.9.2",
     "@nrwl/next": "15.9.2",
-    "@nrwl/react": "15.9.2",
+    "@nrwl/react": "^15.9.2",
     "@nrwl/rollup": "15.9.2",
+    "@nrwl/storybook": "15.9.2",
+    "@nrwl/webpack": "15.9.2",
     "@nrwl/workspace": "15.9.2",
+    "@nx/js": "16.6.0",
     "@rollup/plugin-url": "^7.0.0",
+    "@storybook/addon-essentials": "7.0.18",
+    "@storybook/addon-interactions": "7.0.18",
+    "@storybook/core-server": "7.0.18",
+    "@storybook/jest": "~0.1.0",
+    "@storybook/react-webpack5": "^7.0.18",
+    "@storybook/test-runner": "^0.11.0",
+    "@storybook/testing-library": "~0.2.0",
     "@svgr/rollup": "^6.1.2",
     "@swc/core": "^1.2.173",
     "@swc/helpers": "~0.5.0",
@@ -39,6 +49,7 @@
     "@typescript-eslint/parser": "^5.36.1",
     "babel-jest": "^29.4.1",
     "chai": "^4.3.7",
+    "core-js": "^3.6.5",
     "cypress": "^12.2.0",
     "eslint": "~8.15.0",
     "eslint-config-next": "13.1.1",
@@ -58,11 +69,16 @@
     "react-test-renderer": "18.2.0",
     "rehype-stringify": "^9.0.3",
     "remark": "^14.0.3",
+    "storybook-tailwind-dark-mode": "^1.0.22",
     "swc-loader": "0.1.15",
     "ts-jest": "^29.0.5",
     "ts-node": "10.9.1",
     "typescript": "~4.9.5",
     "unist-util-select": "^4.0.3",
     "unist-util-visit": "^4.1.2"
+  },
+  "dependencies": {
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
   }
 }

packages/components/.storybook/robots.txt

@@ -0,0 +1,3 @@
+User-agent: *
+Allow: /$
+Disallow: /

packages/components/package.json

@@ -16,7 +16,7 @@
     "build": "tsc && vite build && npm run build-tailwind && npm run fix-leaflet",
     "lint": "eslint src --ext ts,tsx --report-unused-disable-directives --max-warnings 0",
     "storybook": "storybook dev -p 6006",
-    "build-storybook": "storybook build",
+    "build-storybook": "storybook build && cp ./.storybook/robots.txt ./storybook-static",
     "build-tailwind": "NODE_ENV=production npx tailwindcss --postcss -c tailwind.config.js -i src/index.css -o ./dist/style.css --minify",
     "prepare": "npm run build",
     "fix-leaflet": "node ./scripts/fix-leaflet.cjs"

packages/core/.storybook/main.ts

@@ -0,0 +1,21 @@
+import type { StorybookConfig } from '@storybook/react-webpack5';
+
+const config: StorybookConfig = {
+  stories: ['../src/**/*.stories.@(js|jsx|ts|tsx|mdx)'],
+  addons: [
+    '@storybook/addon-essentials',
+    '@storybook/addon-interactions',
+    '@nrwl/react/plugins/storybook',
+    'storybook-tailwind-dark-mode'
+  ],
+  framework: {
+    name: '@storybook/react-webpack5',
+    options: {},
+  },
+};
+
+export default config;
+
+// To customize your webpack configuration you can use the webpackFinal field.
+// Check https://storybook.js.org/docs/react/builders/webpack#extending-storybooks-webpack-config
+// and https://nx.dev/packages/storybook/documents/custom-builder-configs

packages/core/.storybook/preview.ts

@@ -0,0 +1,14 @@
+import './tailwind-imports.css';
+
+const preview = {
+    globalTypes: {
+        darkMode: {
+            defaultValue: false, // Enable dark mode by default on all stories
+        },
+        className: {
+            defaultValue: 'dark', // Set your custom dark mode class name
+        },
+    },
+};
+
+export default preview;

packages/core/.storybook/tailwind-imports.css

@@ -0,0 +1,3 @@
+@tailwind base;
+@tailwind components;
+@tailwind utilities;

packages/core/.storybook/tsconfig.json

@@ -0,0 +1,31 @@
+{
+  "extends": "../tsconfig.json",
+  "compilerOptions": {
+    "emitDecoratorMetadata": true,
+    "outDir": ""
+  },
+  "files": [
+    "../../node_modules/@nx/react/typings/styled-jsx.d.ts",
+    "../../node_modules/@nx/react/typings/cssmodule.d.ts",
+    "../../node_modules/@nx/react/typings/image.d.ts"
+  ],
+  "exclude": [
+    "src/**/*.spec.ts",
+    "src/**/*.test.ts",
+    "src/**/*.spec.js",
+    "src/**/*.test.js",
+    "src/**/*.spec.tsx",
+    "src/**/*.test.tsx",
+    "src/**/*.spec.jsx",
+    "src/**/*.test.js"
+  ],
+  "include": [
+    "src/**/*.stories.ts",
+    "src/**/*.stories.js",
+    "src/**/*.stories.jsx",
+    "src/**/*.stories.tsx",
+    "src/**/*.stories.mdx",
+    ".storybook/*.js",
+    ".storybook/*.ts"
+  ]
+}

packages/core/postcss.config.js

@@ -0,0 +1,11 @@
+// libs/shared/ui/postcss.config.js
+const { join } = require('path');
+
+module.exports = {
+  plugins: {
+    tailwindcss: {
+      config: join(__dirname, 'tailwind.config.js'),
+    },
+    autoprefixer: {},
+  },
+};

packages/core/project.json

@@ -34,6 +34,37 @@
         "jestConfig": "packages/core/jest.config.ts",
         "passWithNoTests": true
       }
+    },
+    "storybook": {
+      "executor": "@nrwl/storybook:storybook",
+      "options": {
+        "port": 4400,
+        "configDir": "packages/core/.storybook"
+      },
+      "configurations": {
+        "ci": {
+          "quiet": true
+        }
+      }
+    },
+    "build-storybook": {
+      "executor": "@nrwl/storybook:build",
+      "outputs": ["{options.outputDir}"],
+      "options": {
+        "outputDir": "dist/storybook/core",
+        "configDir": "packages/core/.storybook"
+      },
+      "configurations": {
+        "ci": {
+          "quiet": true
+        }
+      }
+    },
+    "test-storybook": {
+      "executor": "nx:run-commands",
+      "options": {
+        "command": "test-storybook -c packages/core/.storybook --url=http://localhost:4400"
+      }
     }
   }
 }

packages/core/src/ui/Card/Card.stories.tsx

@@ -0,0 +1,48 @@
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+
+import { Card } from './Card';
+
+const meta: Meta<typeof Card> = {
+    component: Card,
+};
+
+export default meta;
+type Story = StoryObj<typeof Card>;
+
+/*
+ *👇 Render functions are a framework specific feature to allow you control on how the component renders.
+ * See https://storybook.js.org/docs/react/api/csf
+ * to learn how to use render functions.
+ */
+
+const blog = {
+    urlPath: "#",
+    title: "Card title goes here",
+    date: "2021-01-01",
+    description: "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed euismod, diam quis accumsan maximus, quam libero porttitor nisl, vita",
+}
+
+export const Primary: Story = {
+    render: () => (
+        <Card className="md:col-span-3">
+            <Card.Title href={`${blog.urlPath}`}>
+                {blog.title}
+            </Card.Title>
+            <Card.Eyebrow
+                as="time"
+                dateTime={blog.date}
+                className="md:hidden"
+                decorate
+            >
+                {blog.date}
+            </Card.Eyebrow>
+            {blog.description && (
+                <Card.Description>
+                    {blog.description}
+                </Card.Description>
+            )}
+            <Card.Cta>Read article</Card.Cta>
+        </Card>
+    ),
+};

packages/core/tailwind.config.js

@@ -0,0 +1,44 @@
+const { createGlobPatternsForDependencies } = require('@nrwl/next/tailwind');
+const { join } = require('path');
+// const defaultTheme = require("tailwindcss/defaultTheme");
+const colors = require("tailwindcss/colors");
+
+module.exports = {
+  content: [
+    join(__dirname, './src/**/*.{js,ts,jsx,tsx}'),
+    ...createGlobPatternsForDependencies(__dirname),
+  ],
+  darkMode: "class",
+  theme: {
+    extend: {
+      // support wider width for large screens >1440px eg. in hero
+      maxWidth: {
+        "8xl": "88rem",
+      },
+      // fontFamily: {
+      //   sans: ["ui-sans-serif", ...defaultTheme.fontFamily.sans],
+      //   serif: ["ui-serif", ...defaultTheme.fontFamily.serif],
+      //   mono: ["ui-monospace", ...defaultTheme.fontFamily.mono],
+      //   headings: ["-apple-system", ...defaultTheme.fontFamily.sans],
+      // },
+      colors: {
+        background: {
+          DEFAULT: colors.white,
+          dark: colors.slate[900],
+        },
+        primary: {
+          DEFAULT: colors.gray[700],
+          dark: colors.gray[300],
+        },
+        secondary: {
+          DEFAULT: colors.sky[400],
+          dark: colors.sky[400],
+        },
+      },
+    },
+  },
+  /* eslint global-require: off */
+  // plugins: [
+  //   require("@tailwindcss/typography")
+  // ],
+};

packages/core/tsconfig.json

@@ -1,5 +1,6 @@
 {
   "compilerOptions": {
+    "baseUrl": ".",
     "jsx": "react-jsx",
     "module": "es2020",
     "moduleResolution": "node",
@@ -22,6 +23,9 @@
     },
     {
       "path": "./tsconfig.spec.json"
+    },
+    {
+      "path": "./.storybook/tsconfig.json"
     }
   ]
 }

packages/core/tsconfig.lib.json

@@ -17,7 +17,11 @@
     "**/*.spec.js",
     "**/*.test.js",
     "**/*.spec.jsx",
-    "**/*.test.jsx"
+    "**/*.test.jsx",
+    "**/*.stories.ts",
+    "**/*.stories.js",
+    "**/*.stories.jsx",
+    "**/*.stories.tsx"
   ],
   "include": ["**/*.js", "**/*.jsx", "**/*.ts", "**/*.tsx"]
 }

site/content/docs/showing-metadata.md

@@ -15,7 +15,7 @@ author: 'Rufus Pollock'
 description: 'An awesome dataset displaying some awesome data'
 modified: '2023-05-04'
 files: ['data.csv']
-groups: ['Awesome']
+group: 'Awesome'
 ---
 
 Built with PortalJS

site/content/guide/index.md

@@ -1,14 +1,16 @@
 ---
 showToc: false
 showSidebar: false
-title: "Markdown-based Websites Guide"
+title: 'Markdown-based Websites Guide'
 disableTitle: true
 description: Create markdown-based websites and data portals, update it, add collaborators and discover markdown superpowers with Flowershow and PortalJS
 ---
 
 <Hero title="Markdown-based Websites" subtitle="Create markdown-based website, update it, add collaborators and discover markdown superpowers" />
 
-# Tutorial 1: Create a website from scratch using markdown and PortalJS
+## Tutorials
+
+### Tutorial 1: Create a website from scratch using markdown and PortalJS
 
 In this tutorial we will walk you through creating an elegant, fully functional website written in simple markdown and published with PortalJS.
 
@@ -20,7 +22,7 @@ By the end of this tutorial you will:
 Below is a screenshot of how the final website will look like:
 ![[tutorial-1-result.png]]
 
-### Setup a sandbox website including live publishing
+#### Setup a sandbox website including live publishing
 
 - Prerequisites: sign up for GitHub and Vercel
 - Navigate to [datopian/flowershow repository](https://github.com/datopian/flowershow)
@@ -28,14 +30,14 @@ Below is a screenshot of how the final website will look like:
 - Let the site build on Vercel
 - Visit the site! Yay! Your site is working! 🎉
 
-### Now, let's edit the front page
+#### Now, let's edit the front page
 
 - Navigate to `content/index.md` file in the site repository
 - Add some text to it
 - Save and watch the site redeploy
 - Visit the site! Yay! Your changes are live! 🎉
 
-### Let's add a page: e.g. about page
+#### Let's add a page: e.g. about page
 
 - Navigate to the `content` folder in the site repository
 - Add `about.md` file with some text
@@ -45,7 +47,7 @@ Below is a screenshot of how the final website will look like:
 > [!tip]
 > Read full tutorial [[create-a-website-from-scratch|here!]]
 
-# Tutorial 2: Editing your site locally on your computer
+### Tutorial 2: Editing your site locally on your computer
 
 In this tutorial, we will walk you through the process of editing your Flowershow website locally on your computer.
 
@@ -61,20 +63,20 @@ Below is a screenshot of how the final website will look like:
 
 ![[tutorial-2-result.png]]
 
-### Clone the repository to your computer
+#### Clone the repository to your computer
 
 - Setup GitHub Desktop app with your GitHub account
 - Grab your site's repository URL
 - Open GitHub Desktop app and clone the repository
 - Yay! You have a copy of your website's repository on your computer! 🎉
 
-### Now, let's edit in Obsidian
+#### Now, let's edit in Obsidian
 
 - Open the `/content` folder of the cloned repository in Obsidian
 - Edit the home page and the about page
 - Create a folder with the reviews of books you've read
 
-### Commit your changes
+#### Commit your changes
 
 - Commit the changes in GitHub Desktop app
 - Push the changes to the remote repository
@@ -83,3 +85,112 @@ Below is a screenshot of how the final website will look like:
 
 > [!tip]
 > Read full tutorial [[edit-a-website-locally|here!]]
+
+### Tutorial 3: Collaborating with others on your website project
+
+In this tutorial, we will guide you through collaborating with others on the same website project using GitHub. 
+
+By the end of this tutorial, you will:
+
+- Understand what a branch is and how to create one.
+- Understand what a pull request (PR) is and how to create one.
+- Learn how to review and merge a PR.
+- Know how to resolve conflicts if they arise.
+- Collaborate with others using GitHub, following best practices.
+
+#### Create a new branch
+
+- Navigate to your site's repository on GitHub
+- Click on the 'Branch' dropdown menu, type a new branch name and press Enter
+- Yay! You've created a new branch! 🎉
+
+#### Now, let's make changes in the new branch
+
+- Switch to the new branch in GitHub Desktop
+- Open the `/content` folder of the repository in Obsidian
+- Edit the `about` page
+- Commit the changes in GitHub Desktop app and push them to the remote repository on GitHub
+
+#### Create a pull request (PR)
+
+- Go back to your site's repository on GitHub
+- Click on 'New pull request'
+- Select your branch from the dropdown menu
+- Write a brief description of your changes, then click on 'Create pull request'
+- Yay! Your changes are ready to be reviewed! 🎉
+
+#### Review and merge a pull request
+
+- Navigate to the 'Pull requests' tab in your repository
+- Open the newly created pull request
+- Review the changes, add comments if necessary
+- If everything is in order, click 'Merge pull request', then 'Confirm merge'
+- Yay! You've merged your changes into the main branch! 🎉
+
+#### Resolving conflicts
+
+- In case of conflicts between your changes and those on the main branch, GitHub will alert you
+- Follow the on-screen instructions to resolve the conflicts and merge your changes
+
+> [!tip]
+> Read full tutorial [[collaborate-on-website-project|here!]] (TBD)
+
+### Tutorial 4: Customising your website locally and previewing your changes locally
+
+In this tutorial, we will dive into the more technical aspects of website customisation, but this time, everything will be done locally. You'll learn how to preview your site on your own machine before pushing changes to the live site, ensuring everything looks and works exactly as you want.
+
+By the end of this tutorial, you will:
+
+- Understand how to preview your site locally.
+- Know how to change your website's title and description.
+- Learn how to customise your website's appearance using Tailwind themes.
+- Understand how to configure the navbar, navigation links, and logo.
+- Learn how to integrate Google Analytics into your website.
+- Be aware of additional customisation options for deeper customisation.
+
+#### Previewing the site locally
+
+- Navigate to your website's repository directory on your computer using command line
+- Install the site's dependencies
+- Start the local development server
+- Visit the local address displayed in your command line. Yay! You can now preview your changes locally, live! 🎉
+
+#### Changing the site title and description
+
+- Perfect! You've personalised your site's title and description! 🎉
+
+#### Configuring the title, description and navbar
+
+- Open the `content/config.mjs` file in your code editor
+- Edit the `title` and `description` fields
+- Edit the fields in the `navbar` field to customise your navbar's title and logo. Then, add navigation links to `navLinks` field (these will be displayed in the navbar). Save and refresh your local site to see the changes.
+
+#### Integrating with Google Analytics
+
+- Still in the `content/config.mjs` file, navigate to the `analytics` field
+- Enter your Google Analytics tracking ID, save and refresh your local site to ensure it's integrated correctly
+- Excellent! Your website is now integrated with Google Analytics! 🎉
+
+#### Customising the Tailwind theme
+
+- Open `tailwind.config.js` file in your code editor
+- Change the light and dark theme colours and fonts to your liking, save and refresh your local site to see the changes
+- Awesome! Your website now has a new look! 🎉
+
+When you're happy with all your changes, use GitHub Desktop to commit your changes and push them back to your GitHub repository.
+
+In addition to these topics, the full tutorial shows you what other customisations options are available and where to find information on these.
+
+> [!tip]
+> Read full tutorial here! (TBD)
+
+
+## Howtos
+
+- [[quickly-create-a-sandbox-website|How to quickly create a sandbox website]]
+- [[edit-text-on-a-single-md-page|How to quickly edit text on a single Markdown-based page]]
+- [[add-a-simple-md-page|How to add a simple Markdown page]]
+- [[edit-or-add-md-pages-locally|How to edit or add Markdown-based pages locally on your computer]]
+- [[how-to-add-images-to-a-md-page|How to add images to a Markdown-based page]]
+- [[publish-obsidian-vault-to-github|How to push an Obsidian vault to a GitHub repository]]
+- [[create-a-simple-catalog-of-anything|How to create a simple catalog of anything in Obsidian]]

site/content/howtos/add-a-simple-md-page.md

@@ -1,13 +1,16 @@
 ---
 title: How to quickly add a simple Markdown-based page
+date: 2023-07-27
+authors: ['Lauren Wigmore', 'Ola Rubaj']
+filetype: 'blog'
 ---
 
-Welcome to this tutorial on how to quickly add a simple Markdown-based page to your website.  The steps here are designed for non-technical contributors. There's no need to know how to code!
+Welcome to this howto on how to quickly add a simple Markdown-based page to your website. The steps here are designed for non-technical contributors. There's no need to know how to code!
 
 > [!important]
-> This "How to" is only recommended for very simple Markdown pages, e.g. those without images, links to other pages, diagrams, or other elements that can't be previewed in GitHub preview mode. 
+> This "How to" is only recommended for very simple Markdown pages, e.g. those without images, links to other pages, diagrams, or other elements that can't be previewed in GitHub preview mode.
 
->[!tip]
+> [!tip]
 > If you are unfamiliar with Markdown (and its different flavours and extra elements supported by Flowershow based websites), check out [this short guide](https://flowershow.app/docs/syntax) on available syntax elements.
 
 ## Steps
@@ -20,15 +23,15 @@ Welcome to this tutorial on how to quickly add a simple Markdown-based page to y
 > [!tip]
 > If you want to add your page to a new subfolder, in the "Name your file..." field, first type the name of the new subfolder, followed by a forward slash, .e.g., `blog/`. After you hit the slash, you'll see the name field gets cleared, but the path before it has been extended with your subfolder name. You can repeat this process if you want to put your file into further nested subfolders. Then, simply type the name of the file with ".md" extension.
 
-5. Paste or write the contents of the file in Markdown format. 
+5. Paste or write the contents of the file in Markdown format.
 6. (Optionally) Switch to the "Preview" mode, by toggling from "Edit" -> "Preview" at the top of the file content, to see a rough visualisation of your changes. Keep in mind though, that the actual website may have different styling and may support additional Markdown elements that GitHub doesn't render on the preview.
-5. When you're happy with the content, click on the “Commit changes...” button. In the "Commit message" field, provide a concise summary of your changes. If necessary, you can add further explanation in the "Extended description" text field. Then select “Commit directly to the main branch”, and hit "Commit changes."
-6. The site is now going to be rebuilt to reflect the changes saved to the `main` branch. This can take up to a few minutes. After this time you should see your page live.
+7. When you're happy with the content, click on the “Commit changes...” button. In the "Commit message" field, provide a concise summary of your changes. If necessary, you can add further explanation in the "Extended description" text field. Then select “Commit directly to the main branch”, and hit "Commit changes."
+8. The site is now going to be rebuilt to reflect the changes saved to the `main` branch. This can take up to a few minutes. After this time you should see your page live.
 
 ## Summary
 
-Congratulations, you've now learned how to create a new Markdown page on your Flowershow-based website. 
+Congratulations, you've now learned how to create a new Markdown page on your Flowershow-based website.
 
-If anything is not clear to you, or you have suggestions on how we can make this 'How to' better, please don't hesitate to let us know. 
+If anything is not clear to you, or you have suggestions on how we can make this 'How to' better, please don't hesitate to let us know.
 
 Happy editing!

site/content/howtos/add-or-edit-content-on-life-itself-ecosystem.md

@@ -3,13 +3,6 @@ title: How to add or edit content on the Life Itself ecosystem page
 isDraft: true
 ---
 
-## Contents
-
-1. [Introduction](#introduction)
-2. [How to edit and add to the site](#how-to-edit-and-add-to-the-site)
-3. [Glossary](#glossary)
-4. [Contact](#contact)
-
 ## Introduction
 
 From the outset, we have argued that any successful mapping effort must be collaborative and participatory. To make it as simple as possible to contribute, we have opened up the site, giving it a wiki-like structure, meaning people can contribute and add items directly - no coding required. We hope this can support the ongoing growth of our contributor community, and empower users to continue in collective efforts to make the map ever more useful and informative.

site/content/howtos/edit-a-page-with-code-editor-or-obsidian.md

@@ -1,5 +1,8 @@
 ---
-title: "How to edit a page with a code editor or Obsidian"
+title: 'How to edit a page with a code editor or Obsidian'
+date: 2023-07-27
+authors: ['Jake Hirsch', 'Ola Rubaj']
+filetype: 'blog'
 isDraft: true
 ---
 

site/content/howtos/edit-or-add-md-pages-locally.md

@@ -1,5 +1,8 @@
 ---
 title: How to edit or add Markdown-based pages locally on your computer
+date: 2023-07-27
+authors: ['Jake Hirsch', 'Ola Rubaj']
+filetype: 'blog'
 ---
 
 ## Intro

site/content/howtos/edit-text-on-a-single-md-page.md

@@ -1,13 +1,16 @@
 ---
-title: How to quickly edit text content on a single Markdown-based page
+title: How to quickly edit text on a single Markdown-based page
+date: 2023-07-27
+authors: ['Ola Rubaj']
+filetype: 'blog'
 ---
 
-Welcome to this tutorial on how to quickly edit text content on a single Markdown-based page.  The steps here are designed for non-technical contributors. There's no need to know how to code!
+Welcome to this tutorial on how to quickly edit text content on a single Markdown-based page. The steps here are designed for non-technical contributors. There's no need to know how to code!
 
 > [!important]
-> This "How to" is only recommended for text changes only, e.g. those that don't include adding images, links to other pages, diagrams, or other elements that can't be previewed in GitHub preview mode. 
+> This "How to" is only recommended for text changes only, e.g. those that don't include adding images, links to other pages, diagrams, or other elements that can't be previewed in GitHub preview mode.
 
->[!tip]
+> [!tip]
 > If you are unfamiliar with Markdown (and its different flavours and extra elements supported by Flowershow based websites), check out [this short guide](https://flowershow.app/docs/syntax) on available syntax elements.
 
 ## Steps

site/content/howtos/how-to-add-images-to-a-md-page.md

@@ -0,0 +1,45 @@
+---
+title: How to add images to a Markdown-based page
+date: 2023-07-27
+authors: ['Jake Hirsch', 'Ola Rubaj']
+filetype: 'blog'
+---
+
+## Intro
+
+Here, you will learn how to add images to a Markdown-based page. These instructions show how to add these images locally, on your computer, so first you need to know how to work locally with GitHub Desktop app and Obsidian. If you're new to these tools, we recommend reading this howto first:
+
+- [[blog/edit-or-add-md-pages-locally|How to edit or add Markdown pages locally]]
+
+Or you can follow these two tutorials to start from scratch:
+
+- [[create-a-website-from-scratch|Tutorial 1: Create a Markdown based website from scratch]]
+- [[edit-a-website-locally|Tutorial 2: Edit your website locally on your computer]]
+
+## Prerequisites
+
+- A GitHub account
+- A GitHub Desktop app
+- Obsidian
+
+## Steps
+
+### Step 1: Set the assets folder as an attachment folder
+
+In Obsidian, in the root of your vault, create a new folder called 'assets'. Then, right click on and select "set as attachment folder". By doing so, all the images you paste into your note will automatically be saved to this folder (instead of being saved to the root, next to all your notes). This is necessary for your website to display embedded images.
+
+### Step 2: Copy and paste your image
+
+Copy whichever image you would like to add and paste it directly into your Obsidian note. You can check that it has been saved to the "assets" folder.
+
+### Step 3: Commit and push
+
+To learn more about this step, see the howto or the tutorials listed in the intro section.
+
+## Summary
+
+Congratulations, you've now learned how to add an image to your Markdown page!
+
+If anything is not clear to you, or you have suggestions on how we can make this 'How to' better, please don't hesitate to let us know.
+
+Happy editing!

site/content/howtos/how-to-format-a-perfect-markdown-based-page.md

@@ -0,0 +1,33 @@
+---
+title: How to format a perfect Markdown-based page
+date: 2023-07-27
+authors: ['Lauren Wigmore', 'Ola Rubaj']
+filetype: 'blog'
+isDraft: true
+---
+
+Welcome to this information guide to help you understand how to format the perfect Markdown-based page for your website. The information here is designed to give you an overview.
+
+## Types of Markdown Styles
+
+There are three types of Markdown options that are supported by Flowershow.
+
+- CommonMark
+- GitHub Flavored Markdown (GFM) - a superset of CommonMark
+- Obsidian Flavored Markdown - a superset of CommonMark with most GFM functionalities plus its own syntax elements, such as wikilinks, callouts, LaTeX, mermaid diagrams, and more.
+
+Each one has extra functionalities building on top of the previous Markdown option.
+
+Flowershow aims to be fully Obsidian compatible since it supports most Obsidian Flavored Markdown syntax elements and therefore, it is the best to use as an editor.
+
+## Useful Links
+
+It would be too complicated (and long) to explain all of the formatting aspects here, so we have included the links below to provide you with this information and more!
+[Flowershow Documents Page](https://flowershow.app/docs/syntax) - Use this page to see all of the useful key elements that are frequently required on Flowershow pages.
+[Obsidian help pages](https://help.obsidian.md/Editing+and+formatting/Obsidian+Flavored+Markdown) - Use this to get more information on Obsidian's supported syntax
+[GFM cheatsheet](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet) - Use this as a quick guide to using Markdown for Github
+
+## Other useful pages
+
+[How to quickly add a simple Markdown-based page](https://guide.portaljs.org/guides/add-a-simple-md-page)
+[How to quickly edit text content on a single Markdown-based page](https://guide.portaljs.org/guides/edit-text-on-a-single-md-page)

site/content/howtos/publish-obsidian-vault-to-github.md

@@ -1,5 +1,8 @@
 ---
 title: How to push an Obsidian vault to a GitHub repository
+date: 2023-07-27
+authors: ['Jake Hirsch', 'Ola Rubaj']
+filetype: 'blog'
 ---
 
 This howto walks you through the process of setting up your Obsidian vault as a GitHub repository. Here are some of the benefits of doing so:
@@ -34,7 +37,7 @@ In this howto, we will use the GitHub Desktop application, an easy-to-use interf
 
 2.6. Add an optional description.
 
-2.7. Make sure the checkbox "Initialize this repository with a README" is unchecked, and "Git Ignore" and "License" are set to "None".
+2.7. Make sure the checkbox "Initialise this repository with a README" is unchecked, and "Git Ignore" and "License" are set to "None".
 
 2.8. Click on "Create Repository".
 

site/content/howtos/quickly-create-a-sandbox-website.md

@@ -1,5 +1,8 @@
 ---
 title: How to quickly create a sandbox website
+date: 2023-07-27
+authors: ['Lauren Wigmore', 'Ola Rubaj']
+filetype: 'blog'
 ---
 
 By the end of this guide you will have a working markdown site you can edit, which gets published automatically online 🎉
@@ -22,13 +25,8 @@ The website will then be deployed. This takes approximately 1 minute.
 
 Once you are on the Congratulations screen, click on the preview of your sandbox website to see the live/published version.
 
-For instructions on how to add and edit pages, we recommend these tutorials:
+For instructions on how to add and edit pages, we recommend these howtos:
 
-- [[edit-a-page-with-code-editor-or-obsidian|How to edit text content on a single Markdown-based page]]
-- [[add-a-simple-md-page|How to add a simple Markdown-based page]]
-
-Here are some other links Vercel links that might be useful for you:
-
-- [Dashboard Features Overview](https://vercel.com/docs/concepts/dashboard-features/overview)
-- [Dashboard Features](https://vercel.com/docs/concepts/dashboard-features)
-- [Projects](https://vercel.com/docs/concepts/projects/project-dashboard)
+- [[howtos/add-a-simple-md-page|How to add a simple markdown page]]
+- [[howtos/edit-text-on-a-single-md-page|How to edit text on a single markdown-based page]]
+- [[howtos/edit-or-add-md-pages-locally|How to edit or add a markdown page locally on your computer]]

site/content/howtos/why-use-these-tools-to-create-a-catalog.md

@@ -1,5 +1,6 @@
 ---
 title: "Why use these tools to create a catalog?"
+isDraft: true
 ---
 
 On this site, we offer a “recipe” which uses a combination of free tools to easily create a directory of information that can be used for multiple purposes. With this method, you can start capturing information quickly and intuitively in a format that is flexible and usable later for various needs. Why does this help us? Because to map information – to collect, organise, structure, and classify it – and present it clearly is a way to make more sense of it and therefore of the world around us. 

site/lib/markdown.mjs

@@ -64,13 +64,6 @@ const parse = async function (source, format, scope) {
               },
               content(node) {
                 return [
-                  h(
-                    'span.invisible.block.h-0.w-0',
-                    { ariaLabel: node.properties.id },
-                    'Read the “',
-                    node.properties.id,
-                    '” section'
-                  ),
                   h(
                     'svg',
                     {

site/next-sitemap.config.js

@@ -2,4 +2,10 @@
 module.exports = {
   siteUrl: process.env.SITE_URL || 'https://portaljs.org',
   generateRobotsTxt: true,
-}
+  robotsTxtOptions: {
+    policies: [
+      { userAgent: '*', disallow: '/people' },
+      { userAgent: '*', disallow: '/?amp=1' },
+    ],
+  },
+};

tsconfig.base.json

@@ -15,10 +15,10 @@
     "skipDefaultLibCheck": true,
     "baseUrl": ".",
     "paths": {
+      "@portaljs/core": ["packages/core/src/index.ts"],
       "@portaljs/portaljs-components": [
         "packages/portaljs-components/src/index.ts"
-      ],
-      "@portaljs/core": ["packages/core/src/index.ts"]
+      ]
     }
   },
   "exclude": ["node_modules", "tmp"]