You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@bookkeeper.apache.org by GitBox <gi...@apache.org> on 2022/03/09 15:47:09 UTC
[GitHub] [bookkeeper] nicoloboschi opened a new pull request #3088: [website] New Website built with Docusaurus v2
nicoloboschi opened a new pull request #3088:
URL: https://github.com/apache/bookkeeper/pull/3088
### Motivation
There was an initial effort to migrate the current website to Docusaurus https://github.com/apache/bookkeeper/pull/2426
All the work has been done under the directory `site2` and using Docusaurus v1. Since the v1 is obsolete and there were a lot of copy-paste from somewhere (I believe from Apache Pulsar) I decided to restart using Docusaurus v2, so I created a `site3` directory.
This pull request contains the whole migration of the website. I have made some changes for different reasons that have to be agreed with the other contributors and I will highlight them in a specific section of this document.
The goal is to not add new sections or improve the current website content but to move that to a modern tooling solution.
NOTE: I do not expect that this PR would be reviewable from the code but doing it in small parts would make the process very slow, this is only a migration of existing content.
**I deployed the final result to**: https://nicoloboschi.github.io/bookkeeper/
### Changes
Migrated the whole website:
* Static pages (homepage, community, project, download, bps)
* Created versioned documentation with sidebars
* Release notes
* Created scripts for the build and instructions in the README.md
#### Migration tweaks
The current documentation is done with Jekyll and Markdown syntax. Docusaurus supports pages writtin with Markdown, MDX (markdown+JSX) and React.js components.
I had to replace the Jekyll syntax with something else. Unfortunately there is not such support builtin in Docusaurus. I got inspired from Apache Pulsar website solution that basically replace the variables before starting the build process (with regex substitution).
I followed some principles in order to keep the documentation the easiest as possible:
- Use Markdown pages as most as possible. Markdown is a static language and it is usable also from a non developer contributors.
- Do not add new things. Do not remove obsolete stuff.
- Use the Docusaurus basic configuration, both for design (navbar, sidebar, footer) and for styling.
#### Design
As the main advantage of migrating to Docusaurus is the maintainability aspect, I decided to only use the builtin features of Docusaurus. Actually the current site is pretty similar to this one.
* Navbar for main contents, versioning and download
* Sidebar for the docs navigation with back and next buttons
* Summary on the right for paragraphs
#### Styling
Docusaurus comes with a default theme with customizable colors palette.
* I took the main BK color and created a palette following the Docusaurus guide.
* I set the same font of the current site.
The current site is built with Bulma. Docusaurus uses Infima by default. I think we should go with the builtin one because:
* We should avoid to write our own css (less stuff to maintain)
* It is not necessary with the current styling (very simple)
#### Main differences
##### Keep only one versioned doc per minor release
Currently there is a versioned doc for each PATCH release. This adds a lot of pages and noise to the website. A patch release is not supposed to edit the website. I decided to keep only the latest patch release for each minor. I documented this in the release instructions (README.md)
The release notes are still there for each release.
##### Release notes
At the moment, each release documentation has his own release notes page. This is ok but :
* it adds a weird step during the release process (you have the template file and so on).
* It is hard to link to the "release notes" because you have to link to the latest release
I decided to migrate to a single page release notes with a paragraph per release.
##### Links
I removed the Github and Twitter buttons from the nav bar. They are now in the footer.
##### Community meeting calendar
Currently this is embedded with a iframe. Iframe is a security hole and it causes Docusaurus to give a lot of errors. I replaced it with an external link.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@bookkeeper.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [bookkeeper] eolivelli commented on pull request #3088: [website] New Website built with Docusaurus v2
Posted by GitBox <gi...@apache.org>.
eolivelli commented on pull request #3088:
URL: https://github.com/apache/bookkeeper/pull/3088#issuecomment-1069296724
I would like to unblock this work.
I will merge this patch if no one objects, it is not a code change, it brings no harm
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@bookkeeper.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [bookkeeper] eolivelli merged pull request #3088: [website] New Website built with Docusaurus v2
Posted by GitBox <gi...@apache.org>.
eolivelli merged pull request #3088:
URL: https://github.com/apache/bookkeeper/pull/3088
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@bookkeeper.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org