palpatine VS Docusaurus

I have been working on building my static site generator palpatine for the last two months. However, I have not had the chance yet to package it up to create my first release yet. When I attempted to package it up a few days ago, I ended up with a lot of errors and bugs that would require lots of time to debug. I plan on sitting with it next week again.

While developing palpatine, I used Makefile to automate the process of building and running the project.

One of the personal projects I love developing is palpatine. I blogged about it here and I am constantly adding new features to it! So far it has reached 5 starts and keeps growing with the help of the open-source community.

Writing unit tests for my static site generator - palpatine, taught me an entirely new testing framework called Catch2. For my Hacktoberfest pull request this year I had done a unit testing contribution for a repository and I am currently working on building a microservice for my cloud computing class which requires us to use Jest for JavaScript unit testing. So, I can say that I have some experience with unit testing and continuing to develop my skills in it.

See the directory called cmake in the root directory of palpatine. Having cmake modules within the directory cmake is commonly used, the purpose of doing is to include() custom CMake functions to be used later in the project.

I have been developing a CLI tool called palpatine for a while now. It is a static site generator (SSG) written in C++ and still under development, ready for the support of the community in GitHub. This Hacktoberfest, I experienced the role of a contributor in open source but in the next Hacktoberfest, I will be participating as a maintainer of palpatine!

Ensuring everything is working as intended makes sense in principle, for example, I currently am developing a static site generator in cpp, palpatine, and as I develop it I stress about writing unit tests for it. Soon enough whenever a bug occurs I will be writing unit tests before debugging it. While writing unit tests though, I need to keep in mind that they won't stick around forever, my ssg tool is rapidly evolving; refactoring, adding new features, fixing bugs and shipping new releases day by day. That said, the unit tests will be obsolete soon enough and I might end up spending more time maintaining unit tests than actually developing the tool. Thus my philosophy at writing unit tests is to write them when they are actually needed, maybe when the consequences of breaking the code are high or when they are solving a specific problem.

While developing palpatine, I found myself browsing through the internet and getting inspired by how other static site generators (SSG) tackled my problems (i.e. supporting md files, stylesheets, exception handling). During this process, it was obvious to me that JavaScript dominated the field of static site generators, as almost all the options I looked at, were Javascript-based. Some of the interesting ones I found were: Docusaurus, Gatsby, Jekyll and Eleventy. They all have their unique features, competing with all other SSGs, and are constantly being maintained by the community in GitHub.   Docusaurus has a showcase page where you can see how other serious projects are using their tool, such as Jest website built with Docusaurus, it is inspiring when you see their pages professionally done. So I initially read their documentation on how to get started, very straightforward, and within minutes I was able to set up my docusaurus site! Key features to note are: easy to use, beautiful themes, precise documentation and customizable.

I ended up with new file FileHandler.h with the base class Handler and the classes MarkdownHandler , TextHandler which inherits the base class. They have virtual functions that are overridden in the derived classes, so that I can use the concept of polymorphism respectively.

To add a new feature to palpatine which is an awesome static site generator written in C++ by Batuhan, I started by filing an issue. While I worked on his repo for adding this new feature, he worked on mine to add the same feature. Here are the detailed instructions for this week's lab. Batuhan also worked on my repo for adding the –config feature for my static site generator, rwar, written in Python. These are awesome repos to check out!

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)