bud
bud copied to clipboard
livebud
Move docs off notion into docusaurus or something?
Notion is a dumpster fire, you have full access to github pages and a million other things, please setup something actually usable. Docusaurus, Jekyll, Hugo and a bunch of other SSGs will create docs (can even be searchable) from markdown source (which I'm p sure you can export from Notion).
@endigma thanks for your comment. Your tone coming over text is a bit harsh, but I'll assume best intentions.
Notion is a temporary solution to be able to share Bud with everyone earlier. I also like the public commenting feature that Notion provides that the other solutions don't.
The documentation should be built with Bud though, dontchya think? 😉
Unless you support markdown source, I'd suggest against it. Some people willing to contribute may not care about sveltekit or react or whatever else is supported, and markdown is more or less the universal language of docs at this point. In addition, readable as plain text.
In addition, a lot of pre-existing software exists that supports full text search and static site generation
Docs will be in /docs as markdown, mdx, or potentially https://markdoc.io/. They'll be pre-rendered to either HTML or Svelte before deploying, depending on how much interactivity is needed.
Docs will also be one page (multiple markdown files) for as long as possible to allow for cmd + f.
I came here to ask the same question, more or less.
To be honest with you, Notion behaves...weird, at least in my case.
I try to move the page up or down with my arrow keys, but would insist on following URL TOC type of thing and while I am in the middle of the page, it takes me straight on top which is so darn annoying (excuse my exasperation, but has happened thrice in a row :laughing: ).
It would be really convenient to have it inside docs as a markdown file or even as generated HTML for the sake of maintaining syntax highlighting styling.
I try to move the page up or down with my arrow keys, but would insist on following URL TOC type of thing and while I am in the middle of the page, it takes me straight on top which is so darn annoying (excuse my exasperation, but has happened thrice in a row 😆 ).
Yes agreed, it's really bad UX. I'll get this switched over soon!
I recommend using https://squidfunk.github.io/mkdocs-material/
It is a theme for mkdocs that has many features build it, some include:
- Diagrams using mermaid.js
- Various formating
- Visual enhancements for better readability
There is more in the reference
The package builds with one command and can be deployed easily to github pages with actions as per docs.
There is another alternative: https://docsify.js.org/
- Themeable
- Searchable
- No static HTML compilation required
