ALAN Manual Is Not Highlighted

[tajmone]

I realized that the HTML version of The ALAN Manual was not being syntax highlighted on the online website due to the missing highlight.js package and stylesheets.

So I've added them to the published branch, but it still won't work due to their main folder starting with and underscore:

• _assets/hjs/highlight.min.js
• _assets/hjs/styles/github.min.css

I think this is due to the fact that we're using Jekyll, which reserves folders beginning with an underscore for its own use (hence I dropped the commit with HLJS addition and force pushed, since it wasn't working and could potentially interfere).

So, our online ALAN Manual is not being highlighted at all (no custom styles are being applied anywhere).

To solve this, we have two options:

1. Drop highlight.js in favour of Highlight.
2. Don't use Jekyll but our own static website.

As for (1), we've already planned to drop highlight.js anyhow, temporarily switching to Highlight until the Rouge syntax for ALAN is ready, then we can switch to Rouge and finally be able to use callouts in the Manual. Right now, the ALAN Manual is the only document using highlight.js, all others are using Highlight already.

As for (2), the alternative to using Jekyll is to disable it by adding a .no-jekyll file in the root of the repository; which would make the whole GHPages branch be served as a static website (i.e. raw HTML contents instead of markdown). Now, this is not a necessary step, since we could solve the issue by dropping highlight.js, but I've nonetheless been looking into it.

I have served static GHPages websites before, using the pandoc tool to convert Pandoc Markdown pages to static HTML. In our case, this would entail creating a new www/ folder in the main repository which would contain the markdown sources, HTML template, image assets, etc. plus a script to build the whole website into HTML and publish it on the published branch — i.e. we would have a www/src/ folder and a www/html/ folder, the former hosting the source material, the latter the statically built website (including the various HTML and PDF docs) that will go into the published branch.

The advantage of this would be that we can use our own custom theme for the website, and exploit the power of pandoc flavoured markdown (which is much richer compared to the GitHub flavoured markdown or CommonMark markdown) as well as using custom PP macros to obtain complex HTML constructs with simple macros. In other words, we would be able to have a much nicer website, with a richer template and cool features like carousels, and other HTML controls which usually require advanced CSS and JS interactions (all wrapped in pandoc/PP macros).

I've been actually looking around for some nice open source web templates, and managed to find five or six templates that could be customized to out project and would look really cool. I can take care of creating the pandoc template, macros, etc., and setup the whole static website sources and build scripts.

Of course, this would add two new dependencies to our project: the pandoc and PP binaries, which are two cross-platform and fully standalone executables, so we could just have a script download them into the www/bins/ folder (ignored by Git) so we can ensure their correct versions are being used.

I'm not sure how you feel about this, but I personally don't like Jekyll in general, and the Jekyll version offered by GHPages is basically a very restrained version of the original Jekyll (no AsciiDoc support, no access to extension). I also don't rally like the GHPages Themes — I find them quite ugly, having worked as a web designer for many years — and I'd rather prefer to have a custom theme that is representative of ALAN, Interactive Fiction, and the whole ALAN Docs project, i.e. a theme which is really themed, which conveys meaning and character.

Also, I believe that having the sources of the website inside our repository gives us better control over the GHPages website.

As a closing note: I'm unable to use the manual/publish.sh script because it uses SSH, and I haven't configured Git to use SSH, only HTTPS (basically, the clone fails due to lack of credentials). So I currently have to manually update the website by copying the files into the various folders (which is what we do for any other doc beside the ALAN Manual anyhow). I'll have a look into how to configure SSH for Git under Windows.