Abridge Refactor

[Jieiku]

I am planning to Refactor Abridge. I will do so under a refactor branch

There will be breaking changes once it goes live, but it will be a long time with lots of testing first.

The overall goal is to make it simpler to configure Abridge, once said and done I want the config.toml file to be cleaner and shorter.

Test using the abridge theme with a mostly empty config.toml (make it so all features use a default value in the template files). This will make it so that it is not strictly necessary to copy the contents of config.toml, and to just run with whatever defaults I have set. There have been a couple times where people have tried to use abridge without copying the config.toml and this theme does not currently run if you do that, there are config values that currently are expected to be set.

Resources files and bundles I want to rework a bit. I am going to test some npm features that make bundling files more dynamic, for instance maybe there is a way to have the npm script check the config.toml file to determine which files to bundle, this would eliminate the need for so many different variants of bundles and the package.json could be reduced to only a few scripts. This will also greatly simplify the head macro.

There are stork/tinysearch files in the static folder. I do not remember how many of these were dynamically generated, but for the files that are generated, add them to the .gitignore file, no need to be distributing them.

SASS/CSS variables. Currently Abridge has some variables that people often want to override (https://github.com/Jieiku/abridge/issues/98), this is possible (https://github.com/getzola/zola/issues/2124) it also means that I do not need to have multiple color variants of the entire css theme, eg abridge-blue, abridge-blueshade, etc...

Make Abridge multi-language. This means adding the multi-language content, and making the demo site multilanguage, this will also allow me to test search features for multi-language sites. https://github.com/Jieiku/abridge/issues/95

The README will obviously also be refactored after most of these changes are implemented.

If anyone thinks of anything else to add to the refactor please post here.

[Jieiku]

Made 99% of the config.toml optional by providing default values in the templates files. Also structured config.toml a little better with header comments for each relevant section. This is a good start, will review it again later, going to work on some of the other items on the list for now.

Also implemented the new json index format for elasticlunr, it eliminates the need for the search_facade.js file that I used previously.

I also reworked the logic of the Head Macro, Now it simply checks if js_bundle is set to true or false, if true it loads the bundle js file, otherwise it loads all the js files individually.

Colors, are now handled via mixins, this makes it simple to edit the colors in a single place. Once I am finished I will outline how to override the variables and imports scss files in the root site. (I may later add a couple more colors as well)

Will probably work on making the npm script dynamic next.

[ddogfoodd]

You mentioned making abridge multi-lingual, are multi-lingual sites currently supported and only the demo misses such content or is there more work to be done, like adding a language switch button etc?

[Jieiku]

That is part of the motivation, because sometimes I get questions about multi-lingual support or features and I honestly don't know how to test or help with that until I try to implement it. There definitely is not a language switch button yet.

I just checked and there are 6 themes that support multi-lingual, most of them redirect you to the index when you change the language, which I do not think I like.

The way that codinfox-z switches the language without redirecting you to the index I like, but they did not provide translations for all pages, only the blog post labeled "Example content". (the rest land on 404 page)

For a business that maybe deploys their site regionally, the way that the Albatros theme handles it might be ideal in some instances because it changes the domain when you switch languages.

For the actual language picker button/menu I liked Albatros and Blow the most. Albatros gets +1 for not requiring js.

Anatole-Zola was the most complete implementation of the ones I tried.

I think I would like a pop out menu like Albatros, keep current page like codinfox-z, and site-wide support like anatole-zola.

For abridge I will implement it similarly to codinfox-z but I hope to implement it in a way that if the translation for a page is missing then it will simply use the primary language as a fallback, either that or I make the build purposely fail when the translations are missing... I have not decided what would be best yet.

Another thing to consider is fonts. Abridge uses the system font stack (specify font-familes that most operating systems have installed) What I would need to research is what fonts are commonly installed in other languages and see if something similar is possible. ( it should fallback to whatever their systems default font is if I do not load any font files. )

https://github.com/Jieiku/abridge/blob/aaff3a63dd20c934c86a26e4ff9cce364ea94ca6/sass/_variables.scss#L116-L119

Theme	Demo	Notes
anatole-zola	Demo	switching language takes you back to index, language aware menu, but hardcoded
Albatros	Demo	different domain per language, on blog posts there is a small flag to change language
codinfox-z	Demo	"Example content" works, switching keeps you on your current page
Blow	Demo	switching language takes you back to index, language aware menu, but not dynamic
kodama	Demo	switching language takes you back to index
HayFlow	Demo	single page site

[Jieiku]

I will try working on the multi-lingual next, should not take very long once I get some free time.

[ddogfoodd]

Ah cool to see your notes, I have also looked at some of these themes to see how it works. If I can help with anything, let me know.

[Jieiku]

@jalemann I finished adding the multi-lingual support (english and french, will add spanish later)

Would appreciate it if you could test it and see if you spot anything I missed.

git clone --branch refactor https://github.com/Jieiku/abridge
cd abridge
zola serve

The search feature currently returns english only results, I know exactly how to fix this, just have not done it yet, will soon.

[ddogfoodd]

@Jieiku looks great, good job! I found one thing still not translated: the date of a post, specifically the written months.

[Jieiku]

Thanks for spotting that @jalemann

I just fixed the date translation, I also fixed the search in the theme, but it looks like the json format also needs fixed in Zola to support multi-lingual (json index fetch is a new feature):

https://github.com/getzola/zola/issues/2167#issuecomment-1526055517

https://github.com/getzola/zola/issues/2193

[Jieiku]

The Refactor is close to complete, it will likely merge shortly after the next version of Zola. (There are a couple bug fixes I am interested in)

For now I will work on the README, and do more testing.

The only other outstanding issues is the syntax highlighting.

I looked those selectors over again, and I cannot find a use for the ones that I commented out... I will likely merge as it is once the next version of Zola is out, and I will just leave that issue open for a while. If nobody complains after 6 months then we are probably not missing anything terribly important.

[welpo]

Since I'm going to be adding multi-lingual support to my theme soon, I took a look at this. Great job!

I noticed the language selector has the "js" class, but I haven't seen where it actually requires JavaScript. In fact, I copied over some code to my theme, without adding any JS, and it seems to work fine.

[Jieiku]

your correct, it only uses css, going to fix that now, thanks for pointing it out.

It was because I copy pasted the element from the adjust icon(switcher) while prototyping and missed it.

[welpo]

The "Copy" text for codeblocks is not translated. Not sure how to access the config file's translations from the JavaScript…

[Jieiku]

I actually don't think theres a straightforward way of doing this, if Zola could build js files from a js template then that would be different. There might be a roundabout way of doing it, but certainly nothing as clean as simply using translations defined in config.toml.

I have a couple other use cases for being able to build a js file with zola from a js template, but unfortunately I have been a bit too busy to work on it, summer time I am always slammed busy.

here is that thread: https://github.com/getzola/zola/issues/2167

https://github.com/getzola/zola/issues/2167#issuecomment-1520746832

EDIT: for now one idea comes to mind.... maybe there is a way to embed the copy button text into the page, and have the javascript simply reveal that value, instead of the javascript showing the text itself. I could picture something like this working. Once I have a bit of time I can see what I can figure out.

EDIT2: The Tabi theme moved to using an icon based copy button, as well as improving the javascript for the copy code block (less lines of code) and improved styling of the code block header. I have followed their implementation of this in abridge with only a couple small tweaks like change color on mouseover hover for the copy button, and I used somewhat smaller svg icons and added them to the icons function, so they can be enabled/disabled like the rest.

[Jieiku]

This is pretty much complete, just waiting for next iteration of Zola, will merge once its released.