clo / cl-site public

Vincent Dardel (@vdardel) on GitLab, 2017-09-29.

hello, this website holds the documentation of many projects. None of them have syntax highlighting for code snippets. I added this in the Cookbook recently thanks to https://github.com/orthecreedence/highlight-lisp Some projects (like ECL) define snippets inside a pre tag with a lisp class, so this would be straightforward to do. However the build instructions don't build anything (nothing in output apart the testpage.html, main.css and a placeholder), let alone the EQL documentation.

I see that the list of pages to build is only the following and an rgrep don't show other uses.

(defparameter *PAGES* 
  (list 
   '((:title . "Test Page") (:slug . "test-page") (:content . "testpage.html")))
  "Each page is an alist containing info to be sent to the template via the context.")

could you provide more instructions on how to build the website with the documentation of other lisp projects, so than I can have a try at adding syntax highlighting ?

regards

(for example, https://common-lisp.net/project/ecl/static/ecldoc/Extensions.html)

Cheshire Yang (@cyang) on GitLab, 2018-04-01.

@vdardel Adding feature like syntax highlighting is low priority at the moment, though I agree I was poor at documenting this. (I say this returning to my code a year later...)

The reason for your observations is that the build tool is incomplete. But I think we'd love your help completing it.

In !5 I have done some more work and if you pull that branch, it now compiles all top-level files within the content directory. My (somewhat jumbled) thoughts are in that merge request.

Please feel free to ask any other questions you may have about the code, I will try my best to answer.

Cheshire Yang (@cyang) on GitLab, 2018-04-01.

Er, with regards to syntax highlighting - If there is a CDN for it, it's best to just insert it within the template - otherwise we could discuss ways to auto-include self-hosted CSS/JS libs. But the consensus right now is that polishing the frontend is a lower priority, and that we should focus on the build tool first. :)

Vincent Dardel (@vdardel) on GitLab, 2018-04-02.

Ok, thanks, I'll have a look. What do you think of my simple merge requests about adding new links on the front page, in the meantime ?

Cheshire Yang (@cyang) on GitLab, 2018-04-02.

I would ping the other members on those issues; decisions about changing site content should best be made as a team consensus.

Administrator (@root) on GitLab, 2018-10-06.

@vdardel rather than saying this isn't a priority, the better answer is that all sites under /project/ are managed by the projects themselves instead of by the main site generator.

What we could do is to offer a library of functions - such as highlighting helpers - to the projects so they can take advantage of features like these without having to find out how by themselves.

Vincent Dardel (@vdardel) on GitLab, 2018-10-11.

I used highlight-lisp (link above) with success several times. It is a matter of adding the lib in static files, I don't think there's a CDN.

By default the lisp code must have a class=lisp to be highlihted, but we can tweak it, for example to highlight all code blocks:

HighlightLisp.highlight_auto({className: null});

So adding highlight-lisp in static files might be a good start, if that makes it available to all other projects.

Erik Huelsmann (@ehuelsmann) on GitLab, 2018-10-11.

I've been searching on the cl-site repository, but can't find any Common Lisp code on the site itself. We could provide the highlighter as part of our site statics (so as to be the CDN for our projects). To get the highlighter implemented on the ECL page you point at, I think we best contact @dkochmanski to ask him to incorporate it.

Daniel Kochmański (@dkochmanski) on GitLab, 2018-10-11.

There are a few things worth mentioning:

• ECL website is https://common-lisp.net/project/ecl/ and it is generated with coleslaw (static site generator).
• ECL documentation is https://common-lisp.net/project/ecl/static/ecldoc/ and it is built with docbook (and uploaded as a whole directory)
• Another datapoint: McCLIM website is also built with coleslaw and as you can see here https://common-lisp.net/project/mcclim/ highlithing works just fine without executing javascript at all. They are compiled from markdown files.

That said I'm not planning to migrate to other technologies / add javascript to the static content at the moment.