modernize website build system

[shinenelson]

The current 'build system' for the documentation website involves TravisCI ( which does not work anymore ) checking out the source, generating the website using Jekyll and then pushing the generated HTML files to the gh-pages branch which is then served at https://forkaweso.me/Fork-Awesome.

This system was inherited from the parent project Font Awesome. It was probably the ideal workflow when it was implemented 4 years ago. GitHub Pages has evolved a lot since then. It now provides a ( sand-boxed ) Jekyll environment out-of-the-box which means that it can generate the documentation website directly from source files.

But we cannot simply lift and drop the system as-is into GitHub's environment because we use a few custom plugins for the generation of the website. GitHub does not allow the use of custom plugins in its environment.

Hence, in order to use GitHub's Pages environment, we will have to 'modernize' the website source files to be compatible to work with GitHub's Pages environment.

[JoaquinDecima]

Ok I return to the offer on this side, although I need to understand well why it was decided to use this repo and not the one on the web to maintain the documentation, I could rewrite the web in HUGO CMS for example. In this way we could keep the documentation in simple markdown files. And I would present a "new" style depending on how you would like it or if you want me to imagine something.

Hugo can run automatically with the GitHub CI. At the same time, I would put together something not too complex or too loaded, but with a newer style if you think so.

If they agree I could make the fork and start putting something together. What I am not sure is why compile it in this repository and not directly in the web repository, which is more convenient to keep the web separate from the project modifications and avoid running the CI if it is not necessary.

[shinenelson]

I could rewrite the web in HUGO CMS for example. In this way we could keep the documentation in simple markdown files.

I did start work on this on my personal fork. However, I chose to use Jekyll because GitHub provides a Jekyll environment by default for GitHub Pages. That also answers :

Hugo can run automatically with the GitHub CI.

If we used Jekyll, we would not even have to bother about the CI for the website at all. GitHub will automatically handle it for us.

You can take a sneak-peek at the progress I made. That is built off of GitHub's CI with no CI configuration whatsoever from my end.

I have not completed the migration yet. I was able to migrate the easiest pages that did not have too many moving parts.

And I would present a "new" style depending on how you would like it or if you want me to imagine something.

That would taking 2 big tasks together which will probably take too long ( that is why #344 and #345 exists as 2 separate issues 😉 ). I would recommend taking up one task at a time and tackling it separately.

If they agree I could make the fork and start putting something together.

If you feel very strongly about Hugo, you can start working on a fork. However, if you would like to take up something that has already made some progress, you can checkout my branch and continue working on the pages that are remaining to be migrated ( I can provide a general direction that I have in my mind, if you would like ).

What I am not sure is why compile it in this repository and not directly in the web repository, which is more convenient to keep the web separate from the project modifications and avoid running the CI if it is not necessary.

( I am not sure if some meaning was lost in translation. ) We do not have a separate web repository yet. I am of the opinion that unless there is some complex things that are happening with the website content, it is best stored in the original source repository. And I believe that our use-case is simple enough to host the documentation in the same repository as the source. That is also partly the reason for this issue - to simplify all of that extra heavy load related to the website and keep it light-weight.

[JoaquinDecima]

Ok in this case if you want you could continue advancing with your Fork to complete the update. And later if it seems to you when the new version is available I can present a new design.

[JoaquinDecima]

Hi again @shinenelson!

I am working on the modernization of the build system. I leave you to see:

https://joaquindecima.github.io/Fork-Awesome/get-started

I forked your repository, you can see the progress here:

https://github.com/JoaquinDecima/Fork-Awesome/tree/gh-pages

After finishing modernizing it, I'm going to put together a new design so you can see if you like it, modifying Bootstrap5 and giving it a new style.

[shinenelson]

First off, I am sorry about the delayed response. I have been busy lately with some personal engagements.

I took a look at your progress and it looks good. I have not had the chance to do an in-depth review, but here is my first take after skimming over the source code

I am happy about how you tackled the icons making them render from Jekyll front-matter. This was exactly how I was going. I had converted a few icons that way; but then I got distracted by some Jekyll smartness that I wanted to explore that would make the rendering even easier.

However, I was intending to do away with all the HTML-based includes and use markdown as much as possible. That, of course, means that we would not get an exact replica of the existing website, but we would be avoiding the maintenance overhead of dealing with HTML and friends. While I also agree that Jekyll is limited in flexibility, I am of the opinion that it can manage the kind of website that we currently have.