cl-cookbook
cl-cookbook copied to clipboard
LispCookbook
Website overhaul?
Continuing the nascent discussion in #279:
we'd enjoy a faster website generator (for local work), and a better looking theme.
Hugo themes for documentation: https://themes.gohugo.io/tags/documentation/
- https://docs.vantage-design.com/ace/getting-started/usage/ (nice one, simple to install and build, npm not required)
Use Coleslaw? https://github.com/coleslaw-org/coleslaw
Material for Mkdocs: https://squidfunk.github.io/mkdocs-material/ (python)
- pretty complete cons: (update 2021)
- need a redirection trick too. Its URL doesn't end in ".html", for example it's "getting-started/", not "getting-started.html".
Searching alternatives to gitbook: https://alternativeto.net/software/gitbook/?license=opensource
- https://rust-lang.github.io/mdBook/ same look, experimental EPUB generator
- https://daux.io/Getting_Started.html multi-language support. Can build a single HTML file, so probably OK for PDF generation. Example in the wild: https://vulkan-tutorial.com/
- …
(edits)
- https://docsify.js.org
I like this idea.
I also like the idea of coleslaw, because it's in lisp. But that's got no technical bearing, I think.
Well, racket website is made in racket. We can’t ignore the impact of this.
Well, racket website is made in racket. We can’t ignore the impact of this.
at least common-lisp.net, Quickdocs and Cliki are made with CL…
I stumbled on Docsify and tried it: https://vindarel.github.io/cl-cookbook/ (edit: we can't see the new site there anymore, my master branch doesn't have the changes anymore. See them on https://github.com/vindarel/cl-cookbook/tree/website-docsify)
I like it and it seems to cover all our needs. It's a full-JS rendering engine that renders the markdown files, we don't have to generate HTML.
What's still there:
- the TOC on the left sidebar, same structure overall
What's new:
- modern, fashion-compliant look and feel
- a welcome screen (it is currently the default)
- a search box (although I experienced a couple issues)
What's missing and could be added:
- syntax highlighting with HighlightLisp, which is better
- a link to the page's source (either with an existing plugin either with our proper code)
- we might loose on Search Engine Optimization, but it's possible to use a Server Side Rendering plugin.
What's possible:
- a dark theme with a switch button
- link to translations page per page
- multi-language support
- more plugins: https://docsify.js.org/#/plugins (edit on github, copy to clipboard button, offline reading,…), https://docsify.js.org/#/awesome
What's impossible:
- to read an url like
…/#/getting-startedwith Emacs' Web Browser… but it's possible to read/getting-started.mdin markdown! We could maybe advertise the alternative url on every page.
What do you all think, any strong objections?
I'll keep this open a few days.
syntax highlighting would be good.
SEO is something to think about, but I'm not too concerned right now. What I am concerned about: will existing links break? IE will we "break google" and break people's bookmarks?
What I am concerned about: will existing links break?
This is a valid concern. Links to the Lisp Cookbook are already everywhere, from search engines through Stack Overflow to books (even if just WIP ones).
big lol, I thought about it once and quickly forgot. Yes they break, it's impossible to merge this.
We can laugh about that^^ yeah a bit but I know I'll use docsify soon again.
Yes they break, it's impossible to merge this.
Not unless we prepare some sort of redirection/routing mechanism from the old links to the new ones. That requires a bit more HTML-generating work though.
I had another quick look at:
- Jekyll documentation plugins
- https://pmarsceill.github.io/just-the-docs/docs/navigation-structure/#navigation-structure
- https://idratherbewriting.com/documentation-theme-jekyll/
They both create the TOC of a page at the beginning, not on the side. And that's important to me.
It seems they don't use .html in URLs (maybe that's modern Jekyll).
- Mkdocs's material theme: https://squidfunk.github.io/mkdocs-material/
The TOC is nice, same about the pages' URL lacking the .html extension.
So both also need a redirection strategy to not break existing links.
docusaurus looks nice with possibility to choose the url root but it's a hell of JS dependencies: https://v2.docusaurus.io/
@vindarel
Below are a few screenshots for reference of cl-cookbook ported to mkdocs with search functionality enabled. The search functionality works great! I did very little styling if any.
See the mkdocs.yml in the root of the project in the mkdocs branch.
I pushed a WIP mkdocs branch here: https://github.com/jgarte/cl-cookbook/tree/mkdocs
I needed to install just two packages in order to build the site:
python -m venv .venv
source .venv/bin/activate
pip install mkdocs pymdown-extensions
With the above shown, I still think it would be cool to build our own "mdbook" like in CL ;() cl-book?
It looks very nice from the screenshots, thanks for trying out.
You could enable Github Pages on your fork, so that you could publish your mkdocs theme and we could see it live (maybe you'll have to push the rendered html into a branch and tell GH Pages to use that as base site).
We'll have to handle transition of URLs (I see you put all files to a doc/ directory). Did you think about a plan?
It looks very nice from the screenshots, thanks for trying out.
No probs, thanks.
Did you think about a plan?
Can you explain further what you mean about think about a plan? Are you referring to the migration of links and not to break existing ones?
You could enable Github Pages on your fork
I'll try that soon and let you know once it is up :)
The best is to not break existing links, but it would be acceptable to have redirection. If I access https://lispcookbook.github.io/cl-cookbook/getting-started.html it would redirect me to …/docs/getting-started.html or whatever the new page is. If we can bend the static site generator to our needs to not break the URLs the better.
It looks like mkdocs has a plugin for redirects called mkdocs-redirects.
You would configure redirects in the redirect_maps setting of your mkdocs.yml file:
https://github.com/mkdocs/mkdocs-redirects#using
The redirect directive syntax looks like this:
plugins:
- redirects:
redirect_maps:
'old.md': 'new.md'
'old/file.md': 'new/file.md'
'some_file.md': 'http://external.url.com/foobar'
So, I'm thinking that the roadmap for implementing this is the following:
- Deploy mkdocs website to personal GitHub pages so we can try it out easily as a community.
- Assess whether we really want to use mkdocs or some other static site generator/solution.
- Collect all redirects.
- Open PR with new site
:100:
Assess whether we really want to use mkdocs or some other static site generator/solution.
I'd prefer, if possible, something faster and easier to install and use, such as Hugo: it's a single binary, and it's really fast. But any upgrade would be improvement. Maybe mkdocs is faster than Jekyll?
Redirects seem supported in Hugo:
- https://gohugo.io/content-management/urls/#aliases
My only objection against hugo is that it would be a bear 🐻 to package for Guix because of all the transitive dependencies.
There have been attempts:
https://github.com/ryanprior/guix-packages/search?l=Scheme&q=hugo
But nothing close yet because of all the work involved.
Even if it does get packaged for Guix, maintaining the hugo package will be a pain.
Maybe Guix needs to get better at packaging golang stuff ;()
mkdocs and coleslaw are easily packaged in Guix:
https://toys.whereis.みんな/?search=coleslaw
https://toys.whereis.みんな/?search=mkdocs
Anyways these are my own biased preferences. Feel free to ignore 🙃