actions-gh-pages VS goldmark

Check out the GitHub action you can use for deploying to GitHub pages: https://github.com/peaceiris/actions-gh-pages.

In addition to just sharing the .html generated files which would likely be cumbersome, you can host the docs on github pages and use something like https://github.com/peaceiris/actions-gh-pages + github actions to upload the documentation from your private repository to a public repo (required for non paid users).

I started by using runs-on: ubuntu-22.04 in this workflow to check if everything works ok. It run without any issues. After that I created PRs to add support for ubuntu-22.04 and ubuntu-latest version to GitHub Actions for Hugo and GitHub Pages Action

As a first-step measure, we changed the CI script to overwrite the gh-pages branch at every run, rather than just appending a new commit. We use this gh-pages action, so it was just a matter of adding a force_orphan: true parameter.

Interesting to note that GitHub stores this workflow in the "main" branch under .github/workflows folder. For more details on this Action please refer the documentation and code at https://github.com/peaceiris/actions-gh-pages.

My first workflow is to build and deploy or preview Client, It runs whenever a push or pull request creates for main branch containing changes to the code of client. It install dependencies and builds vue.js app. After build I use peaceiris/actions-gh-pages to deploy it to Github Pages. If the event is Pull Request then deploy to a sub-directory named preview and commit hash and leave a comment on PR.

If the data fetch from previous step succeeds, the workflow continues by building the static website with Hugo. Hugo is setup using action peaceiris/actions-hugo. When the files are ready, the result is published to GitHub pages, using another GitHub action, peaceiris/actions-gh-pages.

peaceiris/actions-gh-pages@v3 - deploys any folder(s) to gh-pages, can use it for multiple static endpoints

For more information about the actions used and their options, please see Hugo and Github pages on Github.

This quote is quite true. Without automation, we would spend a lot of out time on things that would have to be done repetitively, for example, manually building and deploying your GitHub pages every time there is a change. Luckily, you can easily use GitHub Actions to build and deploy your pages by just pushing your repository to GitHub! You don't even need to do anything except to add a configuration file to your repository. In this post, I will be creating a workflow and using peaceiris/actions-gh-pages@v3 from GitHub Marketplace (it's free).

Goldmark used by Hugo.

Yuin/Goldmark is the new standard Go Markdown processor. Black Friday is older.

As for Hugo with its built-in goldmark Markdown parser and included Footnote extension, a footnote’s HTML begins like this (here, it’s the first footnote in a page):

I am writing a library to convert markdown to HTML. In Go, the common library is https://github.com/yuin/goldmark.

Hugo -> goldmark -> goldmark-highlighting -> chroma

Primarily born out of the annoyance of never-ending README copy & paste, our teammate Adam Babik decided to utilize a Markdown Abstract Syntax Tree parser to generate a naive digest of README snippets and make them easily runnable. This is a prototype (take the happy path!), but we are pleased with the initial results. Illustrated here using Husky - a popular solution to manage git hooks:

Building table in markdown is super easy and well-documented. However, having a bit of formatting within it, like carriage return within a cell as below is not possible by default. Hugo uses Goldmark (a CommonMark implementation in Go) to process the markdown. Apparently it's extremely fast, with this implementation we choose to block any HTML processing d'HTML by default.

Comparison: By default, Eleventy uses Markdown-it; like Astro, Gatsby and Next.js use Remark; and Hugo uses goldmark. As for Astro’s ability to mix components and Markdown on a page, probably the closest analogy to this is the use of MDX files in Gatsby and Next.js; Eleventy and Hugo can’t do this (however, see also “Components,” below, for some words on how Eleventy and Hugo use shortcodes which can provide some degree of code-in-Markdown functionality). Note that migrating an existing site to Astro from any of these other platforms probably will involve far more editing to your existing Markdown content than if you were migrating between two of the non-Astro platforms in this mix.

3rd party libraries: goldmark for converting MD syntax to HTML

The solution to the problem of having to escape many characters in LaTeX markup is solved in a simlar manner, however a combination of Hugo now using the Goldmark renderer and the MathJax API changing quite significantly at version 3.0, it largely needs re-writing. Firstly the script to add the class to the code blocks now looks like this: