-
-
Notifications
You must be signed in to change notification settings - Fork 136
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Website overhaul? #306
Comments
Searching alternatives to gitbook: https://alternativeto.net/software/gitbook/?license=opensource
(edits) |
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. |
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:
What's new:
What's missing and could be added:
What's possible:
What's impossible:
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? |
I like the new theming btw. |
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. |
:( I'm so sorry, you spent a lot of time on this. |
We can laugh about that^^ yeah a bit but I know I'll use docsify soon again. |
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:
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
The TOC is nice, same about the pages' URL lacking the 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/ |
There's also sphinxcontrib-cldomain. |
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 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 ;() |
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? |
No probs, thanks.
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?
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 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:
|
💯
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: |
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 🙃 |
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/
Use Coleslaw? https://github.com/coleslaw-org/coleslaw
Material for Mkdocs: https://squidfunk.github.io/mkdocs-material/ (python)
cons: (update 2021)
The text was updated successfully, but these errors were encountered: