Jekyll to Hugo migration - #979
MuhammadAashirAslam wants to merge 35 commits into
Conversation
Co-authored-by: Gerasimos Chourdakis <gerasimos.chourdakis@ipvs.uni-stuttgart.de>
…#973) Co-authored-by: Gerasimos Chourdakis <gerasimos.chourdakis@ipvs.uni-stuttgart.de>
|
Thank you for the PR and again for all the work in the previous PRs! Building everything together already looks very complete and almost indistinguishable from the previous state. Some issues on the current state:
Could you please also resolve the merge conflicts? They should mostly be trivial. |
# Conflicts: # _config.yml # _includes/news_banner.html # imported/fenicsx-adapter # imported/micro-manager # imported/openfoam-adapter # imported/preeco-orga # imported/tutorials # static/assets/data/news.json
|
Since a new Hugo release is available, let's see: how easy is it to update? |
|
Bumped the versions (also for GO while we at it ) in 95a5610 , other than that nothing interesting caught my eye in the new release. |
There was a problem hiding this comment.
First of all, this port is AMAZING, so well done @MuhammadAashirAslam!
Building this is so easy now and live editting is now actually a reality.
That said, is it possible to live edit files in the included modules? It would be a pretty big downer if this wasn't possible.
I tested the version locally and found some things which I commented on the files. Most important here is that the modules file needs some kind of autogeneration. Currently this is unmaintainable.
The sidebar still has links to the old URLs, so they trigger a redirect and thus a stutter. They should link to the new location.
The sidebar is not really needed. We should still port that to the menus. Maybe in another PR.
We have some weird links that lead to strange behaviour when navigating the website as they are located in multiple places at the same time: The quickstart and the current events.
This looks super weird, we need some solution here.
For the current events: @MakisH maybe the cleanest is to redirect to the entry. Current events could be always visible links above the sidebar, when they exist.
I think the Quickstart needs to decide if it wants to be /tutorial/quickstart/ or /quickstart/.
The community sections don't have section pages yet as they are empty.
Also the minisymposia section is called "Other events", we should maybe fix this @MakisH.
Also the README reads weird. Lines are broken at 80 chars. Could you break on sentence ends. This makes it easier to read.
There was a problem hiding this comment.
This is now actually wrong as we don't build doxygen here anymore.
The file can simply be removed as hugo builds a sitemap
| target = "content/community/contribute/guidelines" | ||
| files = ["! guidelines-adapters.md"] | ||
|
|
||
| # This file is automatically generated by tools/sync_tutorials.py |
There was a problem hiding this comment.
There is no tools/sync_tutorials.py.
Without automation, I would say that this file is unmaintainable.
There was a problem hiding this comment.
This was intended to be here, good catch: #945 (comment)
There was a problem hiding this comment.
There are some problems with this workflow , lets do this after the hugo site is live (so we can discuss it properly in a separate PR)
There was a problem hiding this comment.
Ah. From experience, I can tell that poking at git repos is often easiest with a local shallow clone.
You can create a temporary directory in memory: https://docs.python.org/3/library/tempfile.html#tempfile.TemporaryDirectory
And then git clone --depth=1 all directories you need there.
Then work on these local copies and they clean up automatically.
There was a problem hiding this comment.
For completeness of the review, I would suggest opening a draft PR (or issue) to start the discussion based on the current state. Until then, we should at least document a workaround, so that we can update the modules in the meantime.
Thankyou 🤗
Yes it is possible , you just have to point the modules to your local directory of the module with hugo serve . Example , if i have open foam and the precice website folder in the same directory i can do this. HUGO_MODULE_REPLACEMENTS="github.com/precice/openfoam-adapter -> $(pwd)/../openfoam-adapter" hugo serverFor more you can just add more paths with a separation of a comma HUGO_MODULE_REPLACEMENTS="github.com/precice/openfoam-adapter -> $(pwd)/../openfoam-adapter, github.com/precice/tutorials -> $(pwd)/../tutorials" hugo server
This is a problem i have tried python scripts but they have some drawbacks and occasionally i hit the github too many requests error in the workflow . I will work on this a bit more and start with the tutorials as they require the most changing (adding new tutorials ) while other modules aren't changed that much.
Done 6750fd7
Looking in to this
Done 5af53c3 |
Haha. This is not really easy to use. Could you provide a python wrapper for the modules that builds this override, sets it as an env and then runs hugo with the remaining arguments?
That would be super helpful!
Ah. From experience, I can tell that poking at git repos is often easiest with a local shallow clone. You can create a temporary directory in memory: tempfile.TemporaryDirectory |
| The content of the preCICE webpage is licensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/deed.en). | ||
| Third-party licenses are collected in the `licenses` subfolder. | ||
| preCICE itself is licensed under [LGPL v3](https://www.gnu.org/licenses/lgpl-3.0.en.html). |
There was a problem hiding this comment.
I updated this section in #986, which will need to be adjusted for the currently used libraries.
I would still keep some reference to documentation-theme-jekyll, as there is some continuity from that one.
|
As far as I can tell, the only thing missing now is generating the modules file. I see this as a hard requirement. The local hugo #987 is a nice to have. |
This branch has not been deployed
4 participants
This PR completes the migration of the preCICE website from Jekyll to Hugo.
Summary of Changes
1. Directory Structure & Asset Migration
images/,css/,js/) into Hugo's standardstatic/directory (static/images/,static/css/,static/js/,static/assets/data/).content/tree (content/docs/,content/community/,content/tutorials/,content/about.md).2. Architecture & Dependency Management
config/_default/module.toml,go.mod,go.sum). Imported adapter and tutorial repositories are now fetched and pinned as Hugo modules.config/_default/hugo.toml,module.toml,params.toml).3. Layouts, Partials & Shortcodes
layouts/andlayouts/partials/).{{< warning >}},{{< note >}},{{< tip >}},{{< pagebreak >}}, etc.).aliasesto ensure zero broken bookmarks or external links.4. Search Integration (Algolia)
tools/algolia-index.mjs).public/algolia.jsonduring the production build, which the CLI validates (schema check, record size limits) and uploads using atomic index replacement.5. Offline PDF Generation
tools/pdf-docs.sh).config/pdf/,layouts/partials/pdf/) to build the consolidated offline PDF directly from the Hugo content tree.6. GitHub Actions & Automation Workflows
build.yml: Streamlined CI to test both standard website generation and Algolia dry-run indexing.update-submodules.yml: Modernized to update Hugo module revisions (tools/sync_hugo_modules.py), supporting both daily schedules andrepository_dispatchtriggers from external repositories.update-discourse-data.yml: Scheduled sync for Discourse forum topics, announcements, and FAQs.update-algolia.yml: Automated search index publishing on releases/pushes.7. Documentation & Contributor Setup
README.mdwith streamlined local development instructions (hugo server) and contributing checks (pre-commit).content/docs/docs-meta/) covering site architecture, adding imported repositories, search indexing, and PDF generation.Testing & Verification
hugo server).hugo --gc --minify --cleanDestinationDir --environment production).npm --prefix tools run algolia:index -- --dry-run)../tools/pdf-docs.sh).