Merge pull request #2641 from input-output-hk/djo/2622/future-proof-website

make website more future-proof

Author: Alenar

docs/website/Makefile

@@ -1,4 +1,5 @@
-.PHONY: clean install build serve dev upgrade
+.PHONY: clean install build serve dev lint format upgrade update-current \
+	swizzled-components-upgrade swizzled-components-clean reswizzle-components swizzled-components-apply-patches
 
 package-lock.json:
 	npm install
@@ -27,6 +28,12 @@ clean:
 	rm -rf build
 	rm package-lock.json || true
 
+lint:
+	npm run pretty:check
+
+format:
+	npm run pretty:write
+
 upgrade: clean install
 	# Update to the latest version of react and react-dom when it is supported and does not create dependency conflicts
 	npm install \
@@ -50,8 +57,34 @@ update-current:
 	# Remove the entry for the temporary version in the versions.json file
 	sed -i '/updated/d' versions.json
 
-lint:
-	npm run pretty:check
+swizzled-components-upgrade: swizzled-components-clean reswizzle-components swizzled-components-apply-patches
 
-format:
-	npm run pretty:write
+swizzled-components-clean:
+	@echo "\033[1mRemoving swizzled components\033[0m"
+	rm -rf ./src/theme/Footer ./src/theme/Navbar
+	@echo
+
+reswizzle-components:
+	@echo "\033[1mRe-swizzling Docusaurus components\033[0m"
+	npm run swizzle @docusaurus/theme-classic Footer/Layout -- --eject --typescript
+	npm run swizzle @docusaurus/theme-classic Footer/LinkItem -- --eject --typescript
+	npm run swizzle @docusaurus/theme-classic Footer/Links/MultiColumn -- --eject --typescript
+	npm run swizzle @docusaurus/theme-classic Footer/Logo -- --eject --typescript
+
+	npm run swizzle @docusaurus/theme-classic Navbar/Content -- --eject --typescript --danger
+	npm run swizzle @docusaurus/theme-classic Navbar/Layout -- --eject --typescript --danger
+	npm run swizzle @docusaurus/theme-classic Navbar/MobileSidebar/Layout -- --eject --typescript --danger
+	npm run swizzle @docusaurus/theme-classic Navbar/MobileSidebar/PrimaryMenu -- --eject --typescript --danger
+
+	@echo "\033[1mApplying prettier\033[0m"
+	prettier --write ./src/theme/Footer ./src/theme/Navbar
+	@echo
+
+swizzled-components-apply-patches:
+	@echo "\033[1mTrying to apply custom changes ...\033[33m conflicts must be handled manually\033[0m"
+	$(MAKE) $(wildcard ./upgrade/*.patch)
+
+upgrade/%.patch: src/theme
+	@echo "git apply --verbose --reject ${@}"
+	@git apply --verbose --reject $@ || echo "\033[31mPatch '${@}' failed, check '.rej' files\033[0m"
+	@echo

docs/website/README.md

@@ -1,44 +1,69 @@
 # Website
 
-This website is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator.
+This website is built using [Docusaurus 3](https://docusaurus.io/), a modern static website generator.
 
 ### Installation
 
-```
+```shell
 $ make install
 ```
 
-### Local Development
+### Build
 
+```shell
+$ make build
 ```
-$ yarn start
+
+This command generates static content into the `build` directory and can be served using any static contents hosting
+service.
+
+### Local Development
+
+```shell
+$ make dev
 ```
 
 This command starts a local development server and opens up a browser window. Most changes are reflected live without
 having to restart the server.
 
-### Build
+Alternatively, if you need to simulate GitHub pages hosting environment, you can run
 
-```
-$ make build
+```shell
+$ make serve-static
 ```
 
-This command generates static content into the `build` directory and can be served using any static contents hosting
-service.
+This will create a production build and run it on a Python server as a static content.
 
-### Deployment
+### Content versioning
 
-Using SSH:
+This website gives access to two versions of the documentation:
 
-```
-$ USE_SSH=true npx docusaurus deploy
-```
+- `current`:
+  - Hosts the documentation of the latest Mithril distribution
+  - Shown by default
+  - Source code can be found in `./root`
+- `next`:
+  - Hosts the documentation of the upcoming Mithril distribution under development
+  - Accessible by selecting `Next` in the version dropdown in the navbar
+  - Source code can be found in `./versioned_docs/version-maintained`
 
-Not using SSH:
+#### Versions rotation
 
+When releasing a new distribution, the `current` documentation content can be rotated by using the `next` version with the command:
+
+```shell
+make update-current
 ```
-$ GIT_USER=<Your GitHub username> npx docusaurus deploy
-```
 
-If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to
-the `gh-pages` branch.
+### Upgrading swizzled components
+
+To apply a custom theme to the website, some components from the `docusaurus-theme-classic` have been swizzled.
+If there are changes from the docusaurus side, a makefile command is available to automatically swizzle them again and
+try to apply our custom changes:
+
+> [!WARNING]
+> Conflicts have to be handled manually by the developer.
+
+```shell
+$ make swizzled-components-upgrade
+```