evilsoft
Updating the framework used for docs
Been looking into this a bit on and off, my thoughts are that we should either use the JAMStack or jekyll and gh-pages, any thoughts?
What's you think about docusaurus? I can try to do a migration test, in exchange maybe someone documents the latest ADTs :wink:
take a look at https://github.com/daKmoR/rocket
it's a metaframework of 11ty. really snappy. early days (prerelease) but we use it for https://modern-web.dev
Check out StaticGen, plenty of options. Maybe look at Eleventy or Docusaurus as JavaScript based options? I only say this since Jekyll / Ruby requires minor setup on windows (beats Java though).
Improvements / features wish-list: search - go to the function signature, not just the page (for Combinators, Helpers, etc.) code syntax - pre-render the code snippets source / links - add a link to implementation on GitHub?
BTW:
npm i in the docs directory fails, for node >= 11 (tries to compile old node-sass module).
I've been playing locally with https://v2.docusaurus.io/ as an alternative, I think for my vote it's the real winner. I have a local instance of it with some of the initial conversion done and it seems straight forward so far. I can create a branch and upload it this week if we want to work through it together. Bought a new house and renovating that and just had a baby so crocks has taken a bit of a back burner :') but it'll be good to get this conversion complete
I like it too. It let you works on doc not spend time over the infrastructure of the doc site. I tested it copying the md files from old conf to docusaurus and seems almost ready. I'm trying to create a docusaurus thema to play javascript examples in page with runkit (like ramda docs).
Today I spent a bit 'of time to play with the doc to finish the POC. I tried to put the pieces together until the publication on gh-pages (to avoid preparing everything well but then it fails to publish :laughing:)
branch
https://github.com/davidnussio/crocks/commits/feature/docs-v2
gh-pages
https://davidnussio.github.io/crocks/
TODO
- Add icons
- Working on css style
- Add correct font
- Integrate reading time?
- ~~Search (https://v2.docusaurus.io/docs/search/)~~
- ~~Runkit~~
- ~~Fix scroll (unwanted scroll while switching code/runkit)~~
- ~~Create good layout~~
This is looking real nice, I didn't realise you'd commented was just thinking about this over the weekend
How are you finding the conversion, is there anything that seems to be tripping you up with it or is it pretty straight forward?
It was really simple, I didn't even need the regexp :)
there are two things that tripping me up:
- Home page images, I didn't find the same images
- Replicated menu voice in Sidebar Category and Sidebar Item (e.g. Getting Started → Getting Started) Could be changed in Getting Started → [Installation, Import only what's needed]
gotcha, that seems simple enough on the menu thing,
What do we need on the images front?