mini-ssg VS Docusaurus

#issue-23

Luckily, my newly added test case didn't fail the CI workflow, so my PR got merged eventually.

There are different options to set up GitHub Actions. You can either choose to do it manually or choose from numerous templates. My project, MINI, works just fine with the Node.js template:

With the features in mind, I began by creating an issue on my repo, detailing what I needed to do, and providing suggestions or resources to help me accomplish it. Implementing the code was not too difficult, and I realized that I could add more features to improve my SSG. After being satisfied with how the markdown support works, I began editing the issue to include support for static assets. It is a nice feature to have in my project, as I think images and favicons are common in most web pages today.

My project 💻: mini-ssg Rebase commit 📝: f42e5b6

This week, I decided to work with Luke to implement the new feature of adding support for config file to his SSG tool. The implementation didn't take much time since his code is very clear and doesn't have any major bugs to worry about. With the new feature, the tool now accepts config JSON file when option --config is used. This option will read the config file and generate HTML files based on the options provided within the file, and ignore all other options passed in from the command line. After some modifications, he agreed to merge my pull request

In my static site generator, MINI, I decided to implement 2 new features and created different branches for each of them:

I decided to work on Minh Quan's repo in this lab and implemented Heading1, Heading2 and Links syntax features for his SSG.

Similar to what I did, Vivian also reached me through Slack and asked to review her pull request. While going through the changes that my partner made, I noticed some minor issues. I decided to leave some comments at where they were, explaining how I wanted to change them and included some links for further reading/reference. With the feedback, Vivian quickly fixed the issues and asked me to looked at the code again. Additionally, I asked her to send me on Slack some screenshots of her tests and outputs. After verifying that everything was working as intended, I decided to merge the pull request and not forget to leave her a small token of appreciation.

In testing Luke's code, I found that the --version flag did not correctly print the program name. In addition, his program was not able to correctly read file names that contained spaces. Finally, I noticed a formatting issue in the generated html code. Luke used a library called create-html, which made generating the html very simple, but the formatting of the output was a bit messy (for example, incorrect indentation or a lack of spacing).

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)