Reviewing Open Saas docs

opensaas-sh/README.md

@@ -0,0 +1,53 @@
+# OpenSaas.sh
+
+This is the https://opensaas.sh page and demo app, built with the Open Saas template!
+
+It consists of a Wasp app for showcasing the Open Saas template (+ landing page), while the Astro blog is blog and docs for the Open Saas template, found at https://docs.opensaas.sh.
+
+Inception :)!
+
+## Development
+
+### Demo app (app_diff/)
+
+Since the demo app is just the open saas template with some small tweaks, and we want to be able to easily keep it up to date as the template changes, we don't version (in git) the actual demo app code, instead we version the diffs between it and the template: `app_diff/`.
+
+So because we don't version the actual demo app (`app/`) but its diffs instead (`app_diff`), the typical workflow is as follows:
+
+1. Run `./tools/patch.sh` to generate `app/` from `../template/` and `app_diff/`.
+2. If there are any conflicts (normally due to updates to the template), modify `app/` till you resolve them. Do any additional changes also if you wish.
+3. Generate new `app_diff/`, based on the current updated `app/`, by running `./tools/diff.sh`.
+
+**Running on MacOS**
+
+If you're running the `patch.sh` or `diff.sh` scripts on Mac, you need to install:
+
+- `grealpath` (packaged within `coreutils`),
+- `gpatch`,
+- and `diffutils`.
+
+You should also create aliases for `realpath` and `patch`:
+
+```sh
+brew install coreutils # contains grealpath
+brew install gpatch
+brew install diffutils
+
+echo 'alias realpath="grealpath"' >> ~/.zshrc
+echo 'alias patch="gpatch"' >> ~/.zshrc
+source ~/.zshrc
+```
+
+Make sure not to commit `app/` to git. It is currently (until we resolve this) not added to .gitignore because that messes up diffing for us.
+
+### Blog (blog/)
+
+Blog (and docs in it) is currently tracked in whole, as it has quite some content, so updating it to the latest version of Open Saas is done manually, but it might be interesting to also move it to the `diff` approach, as we use for the demo app, if it turns out to be a good match.
+
+For more info on authoring content for the docs and blog, including information on custom components, see the [blog/README.md](blog/README.md).
+
+## Deployment
+
+App: check its README.md (after you generate it with `.tools/patch.sh`) .
+
+Blog (docs): hosted on Netlify.

opensaas-sh/blog/.gitignore

@@ -0,0 +1,24 @@
+# build output
+dist/
+# generated types
+.astro/
+
+# dependencies
+node_modules/
+
+# logs
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+
+# environment variables
+.env
+.env.production
+
+# macOS-specific files
+.DS_Store
+
+# Local Netlify folder
+.netlify

opensaas-sh/blog/.vscode/extensions.json

@@ -0,0 +1,4 @@
+{
+  "recommendations": ["astro-build.astro-vscode"],
+  "unwantedRecommendations": []
+}

opensaas-sh/blog/.vscode/launch.json

@@ -0,0 +1,11 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "command": "./node_modules/.bin/astro dev",
+      "name": "Development server",
+      "request": "launch",
+      "type": "node-terminal"
+    }
+  ]
+}

opensaas-sh/blog/README.md

@@ -0,0 +1,172 @@
+# OpenSaaS Docs and Blog
+
+This is the docs and blog for the OpenSaaS.sh website, [![Built with Starlight](https://astro.badg.es/v2/built-with-starlight/tiny.svg)](https://starlight.astro.build)
+
+
+## 🚀 Project Structure
+
+Inside of your Astro + Starlight project, you'll see the following folders and files:
+
+```
+.
+├── public/
+├── src/
+│   ├── assets/
+│   ├── components/
+│   ├── content/
+│   │   ├── docs/
+│   │   │   ├── blog/
+│   │   │   ├── guides/
+│   │   │   └── ...
+│   │   └── config.ts
+│   └── env.d.ts
+├── astro.config.mjs
+├── package.json
+└── tsconfig.json
+```
+
+Starlight looks for `.md` or `.mdx` files in the `src/content/docs/` directory. Each file is exposed as a route based on its file name.
+
+Blog posts are in the `src/content/docs/blog/` directory. Use `.mdx` files for blog posts.
+
+Images can be added to `src/assets/` and embedded in Markdown with a relative link.
+
+Static assets, like favicons and banner images, can be placed in the `public/` directory.
+
+We have a number of custom components in `src/components/` that you can use in your blog posts and docs.
+
+##  Custom Components
+
+Custom components in the `src/components/` that replace default Starlight components are imported into the `astro.config.mjs` file:
+
+```js
+components: {
+  SiteTitle: './src/components/MyHeader.astro',
+  ThemeSelect: './src/components/MyThemeSelect.astro',
+  Head: './src/components/HeadWithOGImage.astro',
+  PageTitle: './src/components/TitleWithBannerImage.astro',
+},
+```
+
+Other components can be imported into your blog posts and docs using the `import` statement:
+
+```mdx
+---
+title: "Open SaaS Tutorial"
+date: 2024-12-10
+//...
+---
+import VideoPlayer from '../../../components/VideoPlayer.astro';
+```
+
+### HeadWithOGImage
+
+This component is used to generate the Open Graph (OG) meta tags for the social media preview images for each doc and blog post. 
+
+It checks if a banner image exists in `./public/banner-images` with the same name as the blog post but with a `.webp` extension, e.g. if the blog post is `2024-12-10-open-saas-tutorial.mdx`, it checks for `./public/banner-images/2024-12-10-open-saas-tutorial.webp`. If it does, it uses that image. If it doesn't, it uses the default banner image.
+
+Generally, the default banner image is used for docs, and blog posts use a custom banner image.
+
+### TitleWithBannerImage
+
+This component uses the same image as the `HeadWithOGImage` component to display a banner image above the title of the blog post.
+
+You can use the `hideBannerImage` prop to hide the banner image on the page:
+
+```mdx
+---
+title: "Open SaaS Tutorial"
+date: 2024-12-10
+hideBannerImage: true
+---
+```
+
+Because the same image in `./public/banner-images` is used for social media preview images and the banner image on the doc/blog page, `hideBannerImage: true` will hide the banner image on the doc/blog page, but still use that image for the social media preview image.
+
+### VideoPlayer
+
+This component is a wrapper around the `video` element that adds some default styles.
+
+You can pass three props to the component:
+
+- `src` (required): the path to the video file
+- `lgWidth` (optional): the width of the video player on large screens greater than 425px. If no prop is passed the default is `55%`.
+- `smWidth` (optional): the width of the video player on small screens less than 425px. If no prop is passed the default is `100%`.
+
+```mdx
+---
+title: "Open SaaS Tutorial"
+date: 2024-12-10
+//...
+---
+import VideoPlayer from '../../../components/VideoPlayer.astro';
+
+<VideoPlayer src="/videos/open-saas-tutorial.mp4" lgWidth="75%" smWidth="80%" />
+```
+
+### MyHeader
+
+This component is a wrapper around the `Header` component from the `@astrojs/starlight` package.
+
+It repositions the docs and blog links to the left, and adds a logo and a link to the home page, https://opensaas.sh.
+
+
+## Authoring Content
+
+The docs and blog are written in Markdown or MDX with some additional metadata:
+
+```mdx
+title: We Made the Most Annoying Cookie Banners Ever
+date: 2024-11-26
+tags:
+  - cookie consent
+  - saas
+  - sideproject
+  - hackathon
+subtitle: and it was totally worth it
+hideBannerImage: true
+authors: vince
+```
+
+Most posts are written in MDX, which allows you to use jsx components in your blog posts. It's recommended to use the MDX extension for your editor, such as this one for [VSCode](https://marketplace.cursorapi.com/items?itemName=unifiedjs.vscode-mdx).
+
+### Blog Post Metadata
+`authors` is required and will display the authors of the blog post. To configure a new author, add the proper metadata to `astro.config.mjs` under plugins > starlightBlog > authors:
+
+```js
+authors: {
+  vince: {
+    name: 'Vince',
+    title: 'Dev Rel @ Wasp',
+    picture: '/CRAIG_ROCK.png', // Put author images in the `public` directory.
+    url: 'https://wasp.sh',
+  },
+},
+```
+
+`subtitle` is optional and will display a subtitle below the title of the blog post.
+
+`hideBannerImage` is optional and will hide the banner image in `./public/banner-images` on the blog post page if you only want it to be displayed as the social media preview image (remember, the same image is used for both the social media preview image and the banner image on the blog post page).
+
+### Images
+
+Images to be used in guides and posts are stored in `./src/assets` and are referenced in the blog posts with a relative path.
+
+Banner images used for social media preview images, as well as cover images for blog posts, are stored in `./public/banner-images` and must always use the `.webp` extension. If a banner image is not found, the default banner image is used. (Note: banner images for docs are used only for social media preview images, where for blog posts the are used as social media preview images and as cover images on the blog post page unless the `hideBannerImage` metadata is set to `true`.)
+
+See the [HeadWithOGImage](#headwithogimage) and [TitleWithBannerImage](#titlewithbannerimage) sections for more information.
+
+Always use astro's `Image` component to embed images in your blog posts and docs as Astro will automatically optimize the images for the web.
+
+```mdx
+import { Image } from 'astro:assets';
+import myImage from '../../../assets/my-image.jpg';
+
+<Image src={myImage} alt="My Image" />
+```
+
+## Video
+
+Videos to be used in blog posts are stored in `./src/assets/` and are referenced in the blog posts with a relative path, just like images.
+
+Always use the `VideoPlayer` component to embed videos in your blog posts. See the [VideoPlayer component](#videoplayer) section for more information.

opensaas-sh/blog/astro.config.mjs

@@ -0,0 +1,108 @@
+import { defineConfig } from 'astro/config';
+import starlight from '@astrojs/starlight';
+import starlightBlog from 'starlight-blog';
+
+import tailwind from '@astrojs/tailwind';
+
+// https://astro.build/config
+export default defineConfig({
+  site: 'https://docs.opensaas.sh',
+  trailingSlash: 'always',
+  integrations: [
+    starlight({
+      title: 'OpenSaaS.sh',
+      description: 'Open SaaS is a free, open-source, full-stack SaaS starter kit for React + NodeJS.',
+      customCss: ['./src/styles/tailwind.css'],
+      logo: {
+        src: '/src/assets/logo.webp',
+        alt: 'Open SaaS',
+      },
+      head: [
+        {
+          tag: 'script',
+          attrs: {
+            defer: true,
+            'data-domain': 'docs.opensaas.sh',
+            'data-api': 'https://opensaas.sh/wasparadocs/wasp/event',
+            src: 'https://opensaas.sh/wasparadocs/wasp/script.js',
+          },
+        },
+        {
+          tag: 'script',
+          attrs: {
+            src: 'https://www.googletagmanager.com/gtag/js?id=G-8QGM76GR3Q',
+          },
+        },
+        {
+          tag: 'script',
+          content: `
+          window.dataLayer = window.dataLayer || [];
+          function gtag(){dataLayer.push(arguments);}
+          gtag('js', new Date());
+
+          gtag('config', 'G-8QGM76GR3Q');
+          `,
+        },
+      ],
+      editLink: {
+        baseUrl: 'https://github.com/wasp-lang/open-saas/edit/main/opensaas-sh/blog',
+      },
+      components: {
+        SiteTitle: './src/components/MyHeader.astro',
+        ThemeSelect: './src/components/MyThemeSelect.astro',
+        Head: './src/components/HeadWithOGImage.astro',
+        PageTitle: './src/components/TitleWithBannerImage.astro',
+      },
+      social: {
+        github: 'https://github.com/wasp-lang/open-saas',
+        twitter: 'https://twitter.com/wasplang',
+        discord: 'https://discord.gg/aCamt5wCpS',
+      },
+      sidebar: [
+        {
+          label: 'Start Here',
+          items: [
+            { label: 'Introduction', link: '/' },
+            { label: 'Getting Started', link: '/start/getting-started/' },
+            { label: 'Guided Tour', link: '/start/guided-tour/' },
+          ],
+        },
+        {
+          label: 'Guides',
+          autogenerate: { directory: '/guides/' },
+        },
+        {
+          label: 'General',
+          autogenerate: { directory: '/general/' },
+        },
+      ],
+      plugins: [
+        starlightBlog({
+          title: 'Blog',
+          customCss: ['./src/styles/tailwind.css'],
+          authors: {
+            vince: {
+              name: 'Vince',
+              title: 'Dev Rel @ Wasp',
+              picture: '/CRAIG_ROCK.png', // Images in the `public` directory are supported.
+              url: 'https://wasp.sh',
+            },
+            matija: {
+              name: 'Matija',
+              title: 'CEO @ Wasp',
+              picture: '/matija.jpeg', // Images in the `public` directory are supported.
+              url: 'https://wasp.sh',
+            },
+            milica: {
+              name: 'Milica',
+              title: 'Growth @ Wasp',
+              picture: '/milica.jpg', // Images in the `public` directory are supported.
+              url: 'https://wasp.sh',
+            },
+          },
+        }),
+      ],
+    }),
+    tailwind({ applyBaseStyles: false }),
+  ],
+});