search

evilsoft / crocks

A collection of well known Algebraic Data Types for your utter enjoyment.
https://crocks.dev
ISC License
1.59k stars 102 forks source link

Updating the framework used for docs #459

Open dalefrancis88 opened 4 years ago

dalefrancis88 commented 4 years ago

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?

davidnussio commented 4 years ago

What's you think about docusaurus? I can try to do a migration test, in exchange maybe someone documents the latest ADTs :wink:

bennypowers commented 4 years ago

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

benhormann commented 4 years ago

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).

dalefrancis88 commented 3 years ago

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

davidnussio commented 3 years ago

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).

dalefrancis88 commented 3 years ago

Fair point, you take that i'll get started on the other ADT's

davidnussio commented 3 years ago

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

dalefrancis88 commented 3 years ago

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?

davidnussio commented 3 years ago

It was really simple, I didn't even need the regexp :)

there are two things that tripping me up:

  1. Home page images, I didn't find the same images
  2. 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]

Menu

dalefrancis88 commented 3 years ago

gotcha, that seems simple enough on the menu thing,

What do we need on the images front?

davidnussio commented 3 years ago

Icons, main page layout e sidebar item labels done. Demo

What's still missing?