[site][m] - start of developer faq

site/content/assets/sidebar.json

@@ -10,5 +10,13 @@
       { "title": "Deploying your PortalJS app", "href": "/docs/deploying-your-portaljs-app" }
 
     ]
+  },
+  {
+    "title": "Developer FAQs",
+    "links": [
+      { "title": "Analytics", "href": "/howto/analytics" },
+      { "title": "Page Metadata", "href": "/howto/page-metadata" },
+      { "title": "Sitemaps", "href": "/howto/sitemaps" }
+    ]
   }
 ]

site/content/howto/analytics.md

@@ -0,0 +1,22 @@
+# How to add web analytics?
+
+- Install the following packages
+```
+npm install @flowershow/core
+```
+- Add the following to `/pages/_app.tsx`
+```
+import { pageview } from "@flowershow/core";
+```
+- Add this to the `MyApp` function inside of `_app.tsx`
+```
+  useEffect(() => {
+      const handleRouteChange = (url) => {
+        pageview(url, {YOUR GA_ID});
+      };
+      router.events.on("routeChangeComplete", handleRouteChange);
+      return () => {
+        router.events.off("routeChangeComplete", handleRouteChange);
+      };
+  }, [router.events]);
+```

site/content/howto/page-metadata.md

@@ -0,0 +1,54 @@
+# How to customize the page metadata e.g title, favicon?
+
+- Install the following packages
+
+```
+npm install next-seo
+```
+
+- Add the following tag to the `MyApp` component in `/pages/_app.tsx`
+
+```
+<DefaultSeo {...YOUR ATTRIBUTES GO HERE} />
+```
+
+- You can check all the possible options at the [project readme](https://github.com/garmeeh/next-seo#nextseo-options)
+
+Below is an example of a typical configuration
+
+```
+ <DefaultSeo
+      title="Using More of Config"
+      description="This example uses more of the available config options."
+      canonical="https://www.canonical.ie/"
+      openGraph={{
+        url: 'https://www.url.ie/a',
+        title: 'Open Graph Title',
+        description: 'Open Graph Description',
+        images: [
+          {
+            url: 'https://www.example.ie/og-image-01.jpg',
+            width: 800,
+            height: 600,
+            alt: 'Og Image Alt',
+            type: 'image/jpeg',
+          },
+          {
+            url: 'https://www.example.ie/og-image-02.jpg',
+            width: 900,
+            height: 800,
+            alt: 'Og Image Alt Second',
+            type: 'image/jpeg',
+          },
+          { url: 'https://www.example.ie/og-image-03.jpg' },
+          { url: 'https://www.example.ie/og-image-04.jpg' },
+        ],
+        siteName: 'SiteName',
+      }}
+      twitter={{
+        handle: '@handle',
+        site: '@site',
+        cardType: 'summary_large_image',
+      }}
+    />
+```

site/content/howto/sitemaps.md

@@ -0,0 +1,82 @@
+# How to build a sitemap?
+
+- install the following packages
+
+```
+npm install globby prettier @flowershow/markdowndb
+```
+
+- Add the following script to a `/scripts/sitemap.mjs` file in your project
+
+```
+import { writeFileSync } from "fs";
+import { globby } from "globby";
+import prettier from "prettier";
+import { MarkdownDB } from "@flowershow/markdowndb";
+
+const dbPath = "markdown.db";
+const client = new MarkdownDB({
+  client: "sqlite3",
+  connection: {
+    filename: dbPath,
+  },
+});
+
+const clientPromise = client.init();
+
+export default async function sitemap() {
+  const prettierConfig = await prettier.resolveConfig("");
+  const mddb = await clientPromise;
+  const allFiles = await mddb.getFiles({ extensions: ["mdx", "md"] });
+  const contentPages = allFiles
+    .filter((x) => !x.metadata?.isDraft)
+    .map((x) => `/${x.url_path}`);
+  const pages = await globby([
+    "pages/*.(js|tsx)",
+    "!pages/_*.(js|tsx)",
+    "!pages/api",
+    "!pages/404.(js|tsx)",
+    "!pages/**/\\[\\[*\\]\\].(js|tsx)", // pages/[[...slug]].tsx
+  ]);
+
+  const siteUrl = {YOUR WEBSITE DOMAIN}
+
+  const sitemap = `
+    <?xml version="1.0" encoding="UTF-8"?>
+    <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+      ${pages
+        .concat(contentPages)
+        .map((page) => {
+          const path = page
+            .replace("pages/", "/")
+            .replace("public/", "/")
+            .replace(/\.js|.tsx|.mdx|.md[^\/.]+$/, "")
+            .replace("/feed.xml", "");
+          const route = path === "/index" ? "" : path;
+          return `
+            <url>
+              <loc>${siteUrl}${route}</loc>
+            </url>
+          `;
+        })
+        .join("")}
+    </urlset>
+  `;
+
+  const formatted = prettier.format(sitemap, {
+    ...prettierConfig,
+    parser: "html",
+  });
+
+  if (siteUrl) {
+    writeFileSync("public/sitemap.xml", formatted);
+    console.log("Sitemap generated...");
+  }
+}
+```
+
+- add this to the scripts section in your package.json filename
+
+```
+"prebuild": "./scripts/sitemap.mjs",
+```

site/pages/[...slug].tsx

@@ -63,7 +63,7 @@ export const getStaticProps: GetStaticProps = async ({
   }
 
   // Temporary, docs pages should present the LHS sidebar
-  if (dbFile.url_path.startsWith('docs')) {
+  if (dbFile.url_path.startsWith('docs') || dbFile.url_path.startsWith('howto')) {
     frontMatter.showSidebar = true;
     frontMatter.sidebarTreeFile = 'content/assets/sidebar.json';
   }