317brian opened a new pull request, #14411: URL: https://github.com/apache/druid/pull/14411
### Description This PR updates master to Docusaurus 2. It backs up the previous website directory to `website_old`. We can delete it after we’re ready to merge this PR. Related PRs: - There will be a separate PR that also upgrades the 26.0.0 release branch (Will add link once it's opened) - A PR that upgrades `druid-website-src` to Docusaurus 2. (Will add link once it's opened) - PR that proposes a new publishing process: https://github.com/apache/druid-website-src/pull/392 ### Benefits - No longer EOL backend! - More nesting in the side nav - Support for extended Markdown (MDX), which lets you add Javascript to Markdown pages. ### Changed - The Markdown parser is stricter for Docusaurus2. Impacted docs have already been updated. - The format of redirects. To add a new redirect, follow the ones that have already been converted in website/redirects.json in this PR. - Sidebar syntax - `subcategory` -> `category` - `ids` -> `items` - The [tab syntax](https://docusaurus.io/docs/markdown-features/tabs#customizing-tab-headings) used for things like showing the curl and Python equivalent API calls. - The new config file for the site settings is `website/docusaurus.config.js` ### Stayed the same - Install Docusaurus with `npm/yarn install` and run the site with `npm/yarn start`. - All the website pages, like the home page and "Downloads" page are still in `apache/druid-website-src`. - The source of truth for the CSS and styling of the prod site is `apache/druid-website-src`. I didn’t see a need to style this repo since the main concern would be the Markdown rendering correctly, and they both use the same Markdown parser. - `druid-website-src` still builds the production site - This repo is the source of truth for the docs, sidebar, and redirects. ### Need help on the following: The link checking script and broken link behavior. I copied the link checking script over and updated the path to actually point at the build output from `npm run build`, but the output is different depending on how the filepath is declared: - `const entries = fg.sync(['./build/docs/**/*.html'])` results in:`There are 13232 issues`. That's definitely wrong - `const entries = fg.sync(['./build/docs/latest/*.html'])` results in 1 issue: `Could not find '/docs/latest/design/' linked from './build/docs/latest/index.html`. I think the issue is that it's not going through the directories recursively, so it can't find the file. But if we do the `**` instead of `latest`, we get 13k issues. Neither of these are the actual link I broke intentionally to test the link checker, which Docusaurus 2 detects when you run `npm start`: ``` [INFO] Docs markdown link couldn't be resolved: (./bob.md) in "/Users/brian/my-druid-fork/docs/ingestion/ingestion-spec.md" for version current ``` In the meantime, we can configure Docusaurus 2 to do a one of 2 things on broken links when someone runs the site or tries to build it: We can either set it to log a command line msg like so: [WARNING] Docs markdown link couldn't be resolved: (../ingestion/in.md) in "/Users/brian/my-druid-fork/docs/tutorials/index.md" for version current Or we can surface an error in the rendered site: The user can close the error and navigate around the site still. <hr> <!-- Check the items by putting "x" in the brackets for the done things. Not all of these items apply to every PR. Remove the items which are not done or not relevant to the PR. None of the items from the checklist below are strictly necessary, but it would be very helpful if you at least self-review the PR. --> This PR has: - [x] been self-reviewed. - [ ] using the [concurrency checklist](https://github.com/apache/druid/blob/master/dev/code-review/concurrency.md) (Remove this item if the PR doesn't have any relation to concurrency.) Thanks @ektravel, @writer-jill, @techdocsmith, and @vtlim for helping get this together. -- 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: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
