GAS-ssg VS Docusaurus

For this week's lab I packaged my GAS-ssg using conan and CMake.

For this week's lab I implemented Github Actions for my GAS SSG. First I went back and got my tests from last week working. Even though I implemented testing many of them were failing for reasons I didn't have time to get to, which I thankfully got the chance to get figured out this week. The biggest issue that held me up last week was file input not working if I didn't compile my program as I normally do, which I realized was because I hadn't changed my Visual Studio working directory - so my files were being compiled from one folder while the project was in another - obviously the path was wrong when compiling from the project folder.

I picked Gus's SSG to work on. I had work on his project before because we use the same C++ language. We use same testing framework, which is Catch2. So I generally understand how his SSG and Testing Tool work.

For my part I added some testing capabilities to my SSG using Catch2. Catch2 was super easy to set up and involved downloading one header file from their github repo and including it in my program. There are a number of ways you can choose to have Catch interact with your project, either by having Catch define your main i.e

This week I've been implementing some formatting and linting tools for my SSG via clang-format and clang-tidy. It took some doing to get them set up, at first I was very confused about what exactly clang was vs LLVM, what power tools was vs the command line version, and how to use all of the above.

For this week's lab I added a feature from docusaurus to add tags to my GAS SSG's generated HTML pages for added SEO. I started by logging an issue with a description of the functionality I was looking to add, and started working on it.

In the meantime, Kien had (made a pull request of his own)[https://github.com/gusmccallum/GAS-ssg/pull/20] which, less excitingly, had nothing wrong with it. I had to get git cli to add his as a remote branch, and getting that working took some doing but with his help I got it running and was ready to merge. What ensued was a whole lot of banging my head against a wall figuring out why the merge wouldn't work, but eventually triumph and a successful merge. Somehow I had changed the URL to my origin to his branch's URL, but setting that back to the correct one solved my problems and the merge was complete.

======== Gus's Repo: Github Repo My Repo: Github Repo My Issue: Issue #19 My Pull Request: PR #20

This week was a good way to see what the process of doing proper line by line comparison looks like, with two branches being merged one after the other. First, I logged issues for more relevant return codes and markdown horizontal rule syntax.

I worked with Gus again and his GAS-SSG for this lab. I decided for the markdown support, the syntax I would add would be the "# " header syntax. So I added an Issue for adding the markdown support and created a pull request with the forked branch I made. In the code I modified Gus' if statements that handled the file types to include a block that would look for the ".md" extension and also added a new file type code to represent markdown files. Furthermore, I made some adjustments to the file reader so that when it read a txt file it would handle the header/title features that were implemented by Gus. As for handling the markdown syntax, I added a makeHeader1() function that would take a string and add

Docusaurus is a popular open-source documentation tool primarily designed for product documentation and other technical documentation needs. It was first released in 2017 by Facebook Open Source (now Meta Open Source). Just recently, Docsaurus version 3.0 was released.

// @ts-check // `@type` JSDoc annotations allow editor autocompletion and type checking // (when paired with `@ts-check`). // There are various equivalent ways to declare your Docusaurus config. // See: https://docusaurus.io/docs/api/docusaurus-config import { themes as prismThemes } from "prism-react-renderer"; /** @type {import('@docusaurus/types').Config} */ const config = { title: "My Site", tagline: "Dinosaurs are cool", url: "https://your-docusaurus-test-site.com", baseUrl: "/", onBrokenLinks: "throw", onBrokenMarkdownLinks: "warn", favicon: "img/favicon.ico", organizationName: "facebook", // Usually your GitHub org/user name. projectName: "docusaurus", // Usually your repo name. presets: [ [ "docusaurus-preset-openapi", /** @type {import('docusaurus-preset-openapi').Options} */ ({ docs: { sidebarPath: require.resolve("./sidebars.js"), // Please change this to your repo. editUrl: "https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/", }, blog: { showReadingTime: true, // Please change this to your repo. editUrl: "https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/", }, theme: { customCss: require.resolve("./src/css/custom.css"), }, }), ], ], themeConfig: /** @type {import('docusaurus-preset-openapi').ThemeConfig} */ ({ navbar: { title: "My Site", logo: { alt: "My Site Logo", src: "img/logo.svg", }, items: [ { type: "doc", docId: "intro", position: "left", label: "Tutorial", }, { to: "/api", label: "API", position: "left" }, { to: "/blog", label: "Blog", position: "left" }, { href: "https://github.com/facebook/docusaurus", label: "GitHub", position: "right", }, ], }, footer: { style: "dark", links: [ { title: "Docs", items: [ { label: "Tutorial", to: "/docs/intro", }, ], }, { title: "Community", items: [ { label: "Stack Overflow", href: "https://stackoverflow.com/questions/tagged/docusaurus", }, { label: "Discord", href: "https://discordapp.com/invite/docusaurus", }, { label: "Twitter", href: "https://twitter.com/docusaurus", }, ], }, { title: "More", items: [ { label: "Blog", to: "/blog", }, { label: "GitHub", href: "https://github.com/facebook/docusaurus", }, ], }, ], copyright: `Copyright © ${new Date().getFullYear()} My Project, Inc. Built with Docusaurus.`, }, prism: { theme: prismThemes.github, darkTheme: prismThemes.dracula, }, }), }; export default config;

Facebook's React/Markdown SSG docusaurus does those things: https://docusaurus.io/

Though you may have to use a plugin for responsive images: https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-id...

Docusaurus is an open-source static site generator built on React and has emerged as a popular tool for developing and maintaining product documentation. Its ease of use, extensive features, and robust community support make it a compelling choice for many organizations.

Wondering why Docusaurus (https://docusaurus.io) did not match their needs. Works perfectly fine as a blogging engine for our tech blog.

This is developed by Meta. You can create really nice-looking documentation websites super fast.

Docusaurus, a documentation tool by Facebook, hosts a showcase of other websites that use Docusaurus on their Homepage. The list of websites of this showcase is a typescript files that is maintained by Docusaurus devs, and that you can add your website to through PR: https://github.com/facebook/docusaurus/blob/main/website/src/data/users.tsx

Fix "Edit this page" links at the bottom of each doc (Problem with the Docusaurus build I guess)