LennahSSG VS Docusaurus

This week we got the chance to learn how to package and release our SSGs. For my release I decided to use conan as my package manager and GitLab as my package repository. In order to make my package I had to do a few steps first, I needed to install conan and cmake so I could run the commands. I already had cmake installed from testing Andrew's SSG so that was nice. Then I had to make a new GitLab account and link it to my GitHub account so I could import my repo over to GitLab.

Homepage prototype

After I tested everything I was able to do an interactive rebase in Git to merge all my commits together. This was a really neat feature that allowed me to keep my actions/changes organized and it was super easy to do! If you want to take a look at my rebased commit you can find it here. While it looks like a lot was changed it was a lot more manageable because in reality it was a bunch of separate changes. This feature is great to make the commit history look a lot cleaner because I know I am someone who always tends to miss a few things here and there so the tiny commits tend to pile up. Now I don't have to feel as bad when I notice a small thing that needs changing, I can just rebase the commits!

This week, I focused on adding a new feature to my friends site generator, LENNAH SSG. Using a fork of his project with an issue branch, I was able to add support for config files using --config. I also created a draft pull request in order to better communicate our ideas to each other.

Last week when merging my partner's repo we encountered an issue where several files were in conflict. We opted to delete the conflicting files on his end to allow the merge, rather than going through line by line and seeing what was different and he kept backups so as to reintroduce any code that was cut if he so chose.

I decided the two features I wanted to add were things related to the markdown functionality of my SSG. I added support for inline code using the ` syntax and I also added support for the horizontal rule "---" syntax. Thanks to my classmate Gus, it was really easy to augment the existing code to add new features to the markdown support. All I had to do was add some if statements in the markdown handler section of the file reader to check for ` and --- then I just needed to add a new function for inline code generation. You can find the changes for the inline code implementation here and the horizontal rule implementation here.

When Gus made a pull request for my SSG, I found a few things I wanted him to change. First I wanted him to do the same thing as I did for his SSG; make the txt title/header functionality only work for txt files. Second, I noticed that he had if statements like this:

This week I worked on Joshua Li's SSG, LennahSSG again. I added support for markdown files, with the ability to distinguish and generate appropriate HTML tags for bold and italics.

The hardest part of testing/reviewing Joshua's code was finding anything to critique, it was that good. Like when a prof gives you code to work on, logically organized, concise and without mistakes. His code wouldn't compile using g++ originally, but after ignoring the warnings that came up it compiled fine. I think it was just a case of the compiler being finicky, it wasn't liking the multiple declarations of having prototypes earlier in the file but it ran fine after I ignored those. He also included an executable so it wouldn't have made much of a difference regardless.

It was also very nice to have someone else take a look at your code, I made a few silly mistakes that I would probably never have caught because it made sense in my head, such as my versioning being wrong. (Issue).

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)