IPC144 VS Docusaurus

Reviewing two PRs from a classmate is one of the duties for this project. The PRs, as well as my reviews, are available here and here. Both of the PRs I reviewed were really well-written and detailed, with very few mistakes. It was interesting to observe how different people approached certain changes, such as adding a svg file.

For this assignment we had to contribute to a Seneca repository. I chose the IPC144 repo.

Issue: https://github.com/Seneca-ICTOER/IPC144/issues/64 I worked on the standardized front matter across all markdown pages. This open-source project is the C language course notes of my major program.

And the reason why the web-only artifacts is still appear on the PDF page is because the --excludeSelectors option is not implemented enough. I have to add .clean-btn to the --excludeSelectors, the purpose of this is not to include the "On the page" artifact in side the PDF page. This is the final source code I have implement for this improvement and my pull request

I think I was able to do a good job meeting my goals I gave myself in my planning phase of this release. I was able to finish the issues well on schedule while balancing my other courses like I hoped and I was able to properly audit and fix both issues #122 and #123 without needing too many changes after review. What I learned from those two issues is the importance to read and checkout other issues/pull requests, especially for smaller repos. As I was told in the review for both my issues, I learned that the project recently made changes with how we would format the frontmatter. In PR #142 we no longer use the slug for pages due to inconsistency with links and we also need to include a description to follow the standardized Frontmatter as updated in PR #143.

The first issue I was working on IPC144 Course Note is about improving the usability of the PDF file generated from the website. All contents are generated inside the PDF, however, we want to get this better since some of the pictures are not showing properly, and also the web-only artifacts are still on the PDF, which we do not want it when we use the "PDF" version. convert-to-pdf.sh file would be modified a bit to accomplish this.

Issue #113

PR

As for this pull request, the code review went much more smoothly, with me having to only make minor changes to ensure that it would not cause any errors when built.

2. #issue-107

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)