Website overhaul? - Githubissues

vindarel commented 4 years ago

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

vindarel commented 4 years ago

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

pnathan commented 4 years ago

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.

arademaker commented 4 years ago

Well, racket website is made in racket. We can’t ignore the impact of this.

vindarel commented 4 years ago

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-started with Emacs' Web Browser… but it's possible to read /getting-started.md in 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.

pnathan commented 4 years ago

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?

pnathan commented 4 years ago

I like the new theming btw.

phoe commented 4 years ago

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

vindarel commented 4 years ago

big lol, I thought about it once and quickly forgot. Yes they break, it's impossible to merge this.

pnathan commented 4 years ago

:( I'm so sorry, you spent a lot of time on this.

vindarel commented 4 years ago

We can laugh about that^^ yeah a bit but I know I'll use docsify soon again.

phoe commented 4 years ago

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.

vindarel commented 4 years ago

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.

vindarel commented 3 years ago

docusaurus looks nice with possibility to choose the url root but it's a hell of JS dependencies: https://v2.docusaurus.io/

jgarte commented 1 year ago

There's also sphinxcontrib-cldomain.

https://cl-git.russellsim.org/

jgarte commented 1 year ago

@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?

vindarel commented 1 year ago

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?

jgarte commented 1 year ago

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

vindarel commented 1 year ago

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.

jgarte commented 1 year ago

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

vindarel commented 1 year ago

: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: