Switch to Alternate Frameworks

[sidney-eliot]

This was initially suggested by @sugan-reden here.

I think this is something that should not be decided with haste, as understanding and migrating to new frameworks takes time.

Be sure to comment further suitable frameworks.

Possible Framework Options

The current framework is Quartz 4.0

(sorted in no particular order)

Name	Example Docs	Notes
Editing Quartz's theme	Like seen here https://quartz.jzhao.xyz/showcase
Vue Press (Vue based)	- https://vuepress.vuejs.org/guide/page.html
Gridsome (Vue based)	- https://gridsome.org/docs/components
Hope (Vue Press based)	- https://theme-hope.vuejs.press/guide/layout/footer.html
VitePress (Vite & Vue based)	- https://vitepress.dev/guide/sitemap-generation
Plume (Vue based)	- https://theme-plume.vuejs.press/guide/write/
MyST Markdown	- https://mystmd.org/guide/typography
Curvenote (MyST Markdown based)	- https://curvenote.com/docs/publish/authoring-in-myst - https://phd.row1.ca/introduction
Sphinx	- https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#internal-links
Furo (Sphinx based)	- https://docs.blender.org/manual/en/latest/modeling/meshes/structure.html - https://pradyunsg.me/furo/reference/admonitions
Shibuya (Sphinx based)	- https://shibuya.lepture.com/writing/api/
Book Theme (Sphinx based)	- https://sphinx-book-theme.readthedocs.io/en/stable/sections/sidebar-secondary.html
Starlight (Astro based) (by Astro Team)	- https://starlight.astro.build/environmental-impact/#power-consumption
MK Docs	- https://www.mkdocs.org/user-guide/customizing-your-theme
Material (MK Docs based)	- https://developer.blender.org/docs/features/core/blender_projects - https://squidfunk.github.io/mkdocs-material/customization/
Sphinx RTD (MK Docs based)	- https://events.ccc.de/congress/2024/infos/styleguide.html - https://sphinx-rtd-theme.readthedocs.io/en/stable/
Gitbook	- https://docs.gitbook.com/creating-content/reusable-content - https://sugoi.gitbook.io/lanraragi/installing-lanraragi/docker
Weird Gloop
Docusaurus (React based) (by Meta)	- https://docusaurus.io/docs/configuration	MD: MDX, Search: Algolia
Hugo	Quartz rebuilt the entire thing in nodeJS (Quartz v4), leaving Hugo behind due to many issues and limitations it had. So I think going back to Hugo is not a smart move	MD: Goldmark

When searching for such sites, the following terms can be helpful for finding them: Docs, documentation, wiki, journals, gardens, manual.

Features

Here's a list of good to have aspects as well as things that are pretty essential.

Good to have features:

• Proper preloading of pages (skeleton screens, for example)
• Good load times (ideally fast enough that the reader can click links and instantly look at the next page without noticing the loading screen)
• Export doc to formats like PDF or EPUB

Pretty essential features:

• Open source
• Support generating HTML pages form Markdown pages
• Relatively easy to set up folder structure (can require sitemap or other methods, but it should be something that isn't too difficult to do)
• One or a small handful of centralized CSS files to edit the site's appearance
• An option to edit CSS in the markdown directly for page-specific CSS or even CSS that's limited to specific parts of that markdown page

[sugan-reden]

Good work! 😎 ☀️

---

I think I might have some more to throw into the mix. Although I have less experience with them, and thus less of a opinion, I think they may still be worth considering. They would be Hugo and Docusaurus.

Docusaurus uses React so I'm not really sure about the performance, and Hugo is said to be very performant, but is made in Go and uses Goldmark (markdown flavor) by default to author.

[sugan-reden]

I see you've striken Hugo, I agree it might not have been the best option. 👍
I was mainly putting it out there for feature-comparison.

[sugan-reden]

I think it would be a good idea to perhaps reiterate our main pain points with the current option (reasoning).

For now, these are the ones I can think of. If I missed any, please tell me (^__^)/

• Extension of the markdown flavor (uses Obisidian markdown) is limited.
• Customization via CSS is somewhat clunky
• Customization via plugins is limited (their number/support)
• Performance seems to vary based on the platform (slow on mobile?)
• No PDF or EPUB conversion.

EDIT: After this comment.

[sidney-eliot]

Extension of the markdown flavor (uses Obisidian markdown) is limited.

Could you give an example of a preferred markdown flavor. And maybe one or two things that you think are cool things that aren't possible with Obsidian's markdown.

Customization via CSS is somewhat clunky

True

Customization via plugins is limited (their number/support)

I mean, this is a good to have but not an essential as long as the framework in question offers everything by itself. Not having to use plugins also makes things easier to manage. I often hear people complain about how their word press pages are held together with all kinds of plugins that can be a pain to manage and make things clunky, both for devs and users. And unlike with software where one has to import all kinds of libraries for all kinds of things, a doc is in its design and outline a lot more defined and universal.

Performance seems to vary based on the platform

I tested on my iPad and iPhone (don't have an android currently) and it was pretty responsive (although not instant like on PC. It's about shy of a second), but I think for mobile devices that's totally fine. It's just on PC where one is quickly navigating back and forth through / between pages with a mouse, where an instant page load time is important.

[sugan-reden]

Could you give an example of a preferred markdown flavor.

In my opinion, this would be a flavor that has about the same capabilites as either MyST or markdown-it.

And maybe one or two things that you think are coll things that are possible with Obsidian's markdown.

I'm going to assume you meant things that aren't possible with Obsidian markdown here (if it wasn't, please correct me). And following what I said right above, I have to warn that most of the following examples will come from the mystmd.org, as well as the myst-parser docs. They inherently both use MyST, which itself comes from markdown-it-py, which in turn comes form markdown-it. Some are also from Sphinx.

In all honesty, this isn't too impactful if one is well-versed enough in HTML and CSS already, which is a big reason why staying with Quartz is quite fine option. That said, I envision that not everybody that would want to contribute would be that versed.
This is only how I see it though. Please tell me if you think differently.

A major point for me would be the use of roles and directives, like in reStructuredText (reST) (the markup that Sphinx originally used) allows for an easier extension of the markdown syntax. It allows to bring in more elements from HTML in a user/writer-friendly way. In a sense they are like HTML elements brought into markdown, with roles being more for inline and directives being more for block types of content. There is a small introduction to the concept, here. Things like:

• The <abbr> element
• The ability to call class directly of objects in markdown with .attributes, see the glossary below for an example.
• Definition lists and glossaries
• A special role to differentiate keyboard input from inline literal text / inline code.
• Field lists, although this would probably be more suited for code docs.
• Callouts/Admonition/Asides (these have many names) but blocks where you can call CSS classes directly in markdown, and assign reference names (or tags) to link to them more easily in markdown.
  This particularly is a good example to demonstrate what is a directive and how versatile/powerful it can be. Imagine being able to extend markdown to specify rendering behaviors with whichever type of directive.
• Containers, grids, cards and tabs directly in markdown.
• More control over images and the addition of figures (images with captions and legends)
• The Cross-references has many examples of cross-referencing examples with a bit more visual oohmf and redirection. Try hovering on some :)

A lot of these visual examples also come from sphinx-design, an extension for sphinx with cool visual stuff. One thing I would have probably liked trying to implement is card (more specifically card images) like Blender does in their manual's home page, for this page of the handbook.
Also, I think some example images from the handbook would benefit from having proper figure-like appearances (i.e. with captions and legends).
One other thing may be the steps from Astro's Starlight. Although, this arguably may be a bit less impactful for the handbook.

I just realized while digging that they have a desciption that is bit more fitting in their Syntax Extensions page (which has even more examples):

MyST-Parser is highly configurable, utilising the inherent “plugability” of the markdown-it-py parser. The following syntaxes are optional (disabled by default) and can be enabled via the sphinx conf.py configuration file (see also Configuration). Their goal is generally to add more Markdown friendly syntaxes; often enabling and rendering markdown-it-py plugins that extend the CommonMark specification.

The key to me is this part:

Their goal is generally to add more Markdown friendly syntaxes; often enabling and rendering markdown-it-py plugins that extend the CommonMark specification.

Which is what I wanted to describe earlier.
These are only a couple. But I think most of them could be applicable to this project.

---

This is unrelated, but one of the main reasons I was digging so much, even in the past, was to see if I could implement or have the <ruby> HTML element directly in markdown, for a -- if you will -- Japanese Handbook I was building. Docs here, scroll a tiny bit for visual examples.
This is the element that allows to add furigana in Japanese, for example.

Please excuse the typos, I am dead-tired today lol. Cheers 🍹

[sugan-reden]

I also agree that too many plugins would be bad too. In any case I would try to maintain the number of them low, as such, we would simply not import or opt-in for those we don't need. For example, maybe we wouldn't need the math plugins in Sphinx.

I tested on my iPad and iPhone (don't have and android currently) and it was pretty responsive (although not instant like on PC. It's about shy of a second), but I think for mobile devices that's totally fine. It's just on PC where one is quickly navigating back and forth through / between pages with a mouse, where an instant page load time is important.

This is also true. I have to admit I had only tested with my phone on a single browser. I will aim to conduct a bit more in-depth testing in the future, on both mobile and PC.

I will also edit the original comment in consequence.

Personally, I am leaning towards these as my top picks for now:

#	Name
0	Quartz
1	VuePress (any theme)
2	VitePress
3	Sphinx (any theme)

How about you?

[sidney-eliot]

One thing I would have probably liked trying the implement card (more specifically card images) like Blender does in their manual's home page

I wanted something exactly like this, not just for the hotkeys, but also other parts. One could use for some of the pages for an in page table of content where one links to things on the page with cards like that

Also, I think some example images from the handbook would benefit from having proper figure-like appearances

Yeah, different font color / font properties could be good, currently I simply make captions below images italic

I would also like to have proper syntax highlighting of code blocks for when I maybe delve more into game engine / shader programming, something which quartz does not have.

Some further features you mentioned that I quite like:

• Abbreviations & {.glossary}
• keyboard input buttons
• Those admonitions that also allow for tabs beside each other, would be interesting, one could, for example, show an open GL and direct X approach beside each other. I think specifically when the handbook starts covering more things in the tech art direction, this could be quite helpful.

I also find steps to be quite cool

How about you?

I'm still quite undecided, but using one that is MyST based is something I'm thinking about or Furo / Material. And starlight also being one, as I'm a fan of the underlying framework.

Cheers 🫖

[sugan-reden]

I wanted something exactly like this, not just for the hotkeys, but also other parts. One could use for some of the pages for an in page table of content where one links to things on the page with cards like that

That's indeed a nice idea ^^ I'd like that too 👍

Yeah, different font color / font properties could be good, currently I simply make captions below images italic

Yes 👍 I would also consider the layout, and centering most of them.

I would also like to have proper syntax highlighting of code blocks for when I maybe delve more into game engine / shader programming, something which quartz does not have.

Did you mean something more powerful or different than this? Or did the highlighting not satisfy what you had in mind?

Some further features you mentioned that I quite like:

• Abbreviations & {.glossary}
• keyboard input buttons
• Those admonitions that also allow for tabs beside each other, would be interesting, one could, for example, show an open GL and direct X approach beside each other. I think specifically when the handbook starts covering more things in the tech art direction, this could be quite helpful.

I also find steps to be quite cool

Oh! Yeah 🤟, I quite like all of these too, especially the tabs hehe
I'm excited to get into the Tech Art aspects too 🤯

I'm still quite undecided, but using one that is MyST based is something I'm thinking about or Furo / Material. And starlight also being one, as I'm a fan of the underlying framework.

Noice 👌. Furo and Starlight are very nice ✨
Speaking about Material though, that makes me think to mention that, if you're interested, there are Material themes for Sphinx too (e.g. [1], [2]), meaning we could still use MyST with Material.

There's no super rush here, so no worries. It's far from an being un-impactful decision ^^.

Cheers 🧉