apache · techdocsmith · Aug 17, 2023 · Feb 2, 2023 · Feb 2, 2023 · Feb 2, 2023
diff --git a/.github/workflows/static-checks.yml b/.github/workflows/static-checks.yml
@@ -166,7 +166,7 @@ jobs:
         run: |
           (cd website && npm install)
           cd website
-          npm run link-lint
+          npm run build
           npm run spellcheck
 
       - name: web console

diff --git a/.gitignore b/.gitignore
@@ -29,6 +29,13 @@ integration-tests/gen-scripts/
 /bin/
 *.hprof
 **/.ipynb_checkpoints/
+website/.yarn/
+website/node_modules/
+website/.docusaurus/
+website/build/
+
+# Local Netlify folder
+.netlify
 *.pyc
 **/.ipython/
 **/.jupyter/

diff --git a/README.md b/README.md
@@ -87,7 +87,11 @@ Use the built-in query workbench to prototype [DruidSQL](https://druid.apache.or
 
 See the [latest documentation](https://druid.apache.org/docs/latest/) for the documentation for the current official release. If you need information on a previous release, you can browse [previous releases documentation](https://druid.apache.org/docs/).
 
-Make documentation and tutorials updates in [`/docs`](https://github.com/apache/druid/tree/master/docs) using [MarkDown](https://www.markdownguide.org/) and contribute them using a pull request.
+Make documentation and tutorials updates in [`/docs`](https://github.com/apache/druid/tree/master/docs) using [Markdown](https://www.markdownguide.org/) or extended Markdown [(MDX)](https://mdxjs.com/). Then, open a pull request.
+
+To build the site locally, you need Node 16.14 or higher and to install Docusaurus 2 with `npm|yarn install`  in the `website` directory. Then you can run `npm|yarn start` to launch a local build of the docs.
+
+If you're looking to update non-doc pages like Use Cases, those files are in the [`druid-website-src`](https://github.com/apache/druid-website-src/tree/master) repo.
 
 ### Community
 

diff --git a/distribution/asf-release-process-guide.md b/distribution/asf-release-process-guide.md
@@ -370,20 +370,37 @@ $ svn commit -m 'add 0.17.0-rc3 artifacts'
 
 ### Update druid.staged.apache.org
 
+This repo is the source of truth for the Markdown files. The Markdown files get copied to `druid-website-src` and built there as part of the release process. It's all handled by a script in that repo  called `do_all_things`.
+
+For more thorough instructions and a description of what the `do_all_things` script does, see the [`druid-website-src` README](https://github.com/apache/druid-website-src)
+
 1. Pull https://github.com/apache/druid-website and https://github.com/apache/druid-website-src. These repositories should be in the same directory as your Druid repository that should have the release tag checked out.
 
-2. From druid-website, checkout branch `asf-staging`.
+2. From `druid-website`, checkout branch `asf-staging`.
 
-3. From druid-website-src, create a release branch from `master` and run `./release.sh 0.17.0 0.17.0`, replacing `0.17.0` where the first argument is the release version and 2nd argument is commit-ish. This script will:
+3. From `druid-website-src`, create a release branch from `master`, such as `27.0.0-docs`.
+   1. Update the version list in `static/js/version`.js with the version you're releasing and the release date. The highest release version goes in position 0. 
+   1. In `scripts`, run: 
+
+   ```python
+   # Include `--skip-install` if you already have Docusaurus 2 installed in druid-website-src. 
+   # The script assumes you use `npm`. If you use `yarn`, include `--yarn`.
 
-* checkout the tag of the Druid release version
-* build the docs for that version into druid-website-src
-* build druid-website-src into druid-website
-* stage druid-website-src and druid-website repositories to git.
+   python do_all_things.py -v VERSION --source /my/path/to/apache/druid
+   ```
+
+
+4. Make a PR to the src repo (https://github.com/apache/druid-website-src) for the release branch. In the changed files, you should see the following:
+  - In `published_versions` directory: HTML files for `docs/VERSION` , `docs/latest`, and assorted HTML and non-HTML files 
+  - In the `docs` directory at the root of the repo, the new Markdown files.
+
+    All these files should be part of your PR to `druid-website-src`.
+   <br />
+    Verify the site looks fine and that the versions on the homepage and Downloads page look correct. You can run `http-server` or something similar in `published_versions`.
 
-4. Make a PR to the src repo (https://github.com/apache/druid-website-src) for the release branch, such as `0.17.0-docs`. 
 
-5. Make another PR to the website repo (https://github.com/apache/druid-website) for the `asf-staging` branch. Once the website PR is pushed to `asf-staging`, https://druid.staged.apache.org/ will be updated near immediately with the new docs.
+
+5. Make a PR to the website repo (https://github.com/apache/druid-website) for the `asf-staging` branch using the contents of `published_versions` in `druid-website-src`. Once the website PR is pushed to `asf-staging`, https://druid.staged.apache.org/ will be updated near immediately with the new docs.
 
 ### Create staged Maven repo
 

diff --git a/docs/api-reference/data-management-api.md b/docs/api-reference/data-management-api.md
@@ -29,7 +29,9 @@ This document describes the data management API endpoints for Apache Druid. This
 
 While segments may be enabled by issuing POST requests for the datasources, the Coordinator may again disable segments if they match any configured [drop rules](../operations/rule-configuration.md#drop-rules). Even if segments are enabled by these APIs, you must configure a [load rule](../operations/rule-configuration.md#load-rules) to load them onto Historical processes. If an indexing or kill task runs at the same time these APIs are invoked, the behavior is undefined. Some segments might be killed and others might be enabled. It's also possible that all segments might be disabled, but the indexing task can still read data from those segments and succeed.
 
-> Avoid using indexing or kill tasks and these APIs at the same time for the same datasource and time chunk.
+:::info
+ Avoid using indexing or kill tasks and these APIs at the same time for the same datasource and time chunk.
+:::
 
 `POST /druid/coordinator/v1/datasources/{dataSourceName}`
 

diff --git a/docs/api-reference/json-querying-api.md b/docs/api-reference/json-querying-api.md
@@ -3,8 +3,12 @@ id: json-querying-api
 title: JSON querying API
 sidebar_label: JSON querying
 ---
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
 
 <!--
+
   ~ Licensed to the Apache Software Foundation (ASF) under one
   ~ or more contributor license agreements.  See the NOTICE file
   ~ distributed with this work for additional information
@@ -33,7 +37,7 @@ In this topic, `http://SERVICE_IP:SERVICE_PORT` is a placeholder for the server
 Submits a JSON-based native query. The body of the request is the native query itself.
 
 Druid supports different types of queries for different use cases. All queries require the following properties:
-* `queryType`: A string representing the type of query. Druid supports the following native query types: `timeseries`, `topN`, `groupBy`, `timeBoundaries`, `segmentMetadata`, `datasourceMetadata`, `scan`, and `search`. 
+* `queryType`: A string representing the type of query. Druid supports the following native query types: `timeseries`, `topN`, `groupBy`, `timeBoundaries`, `segmentMetadata`, `datasourceMetadata`, `scan`, and `search`.
 * `dataSource`: A string or object defining the source of data to query. The most common value is the name of the datasource to query. For more information, see [Datasources](../querying/datasource.md).
 
 For additional properties based on your query type or use case, see [available native queries](../querying/querying.md#available-queries).
@@ -49,13 +53,16 @@ For additional properties based on your query type or use case, see [available n
 
 ### Responses
 
-<!--DOCUSAURUS_CODE_TABS-->
+<Tabs>
+
+<TabItem value="1" label="200 SUCCESS">
+
 
-<!--200 SUCCESS-->
+*Successfully submitted query*
 
-*Successfully submitted query* 
+</TabItem>
+<TabItem value="2" label="400 BAD REQUEST">
 
-<!--400 BAD REQUEST-->
 
 *Error thrown due to bad query. Returns a JSON object detailing the error with the following format:*
 
@@ -69,17 +76,19 @@ For additional properties based on your query type or use case, see [available n
 ```
 For more information on possible error messages, see [query execution failures](../querying/querying.md#query-execution-failures).
 
-<!--END_DOCUSAURUS_CODE_TABS-->
+</TabItem>
+</Tabs>
 
 ---
 
 ### Example query: `topN`
 
-The following example shows a `topN` query. The query analyzes the `social_media` datasource to return the top five users from the `username` dimension with the highest number of views from the `views` metric. 
+The following example shows a `topN` query. The query analyzes the `social_media` datasource to return the top five users from the `username` dimension with the highest number of views from the `views` metric.
 
-<!--DOCUSAURUS_CODE_TABS-->
+<Tabs>
+
+<TabItem value="3" label="cURL">
 
-<!--cURL-->
 
 ```shell
 curl "http://ROUTER_IP:ROUTER_PORT/druid/v2?pretty=null" \
@@ -103,7 +112,9 @@ curl "http://ROUTER_IP:ROUTER_PORT/druid/v2?pretty=null" \
   ]
 }'
 ```
-<!--HTTP-->
+</TabItem>
+<TabItem value="4" label="HTTP">
+
 
 ```HTTP
 POST /druid/v2?pretty=null HTTP/1.1
@@ -131,7 +142,8 @@ Content-Length: 336
 }
 ```
 
-<!--END_DOCUSAURUS_CODE_TABS-->
+</TabItem>
+</Tabs>
 
 #### Example response: `topN`
 
@@ -179,9 +191,10 @@ In this query:
 * The `upvoteToPostRatio` is a post-aggregation of the `upvoteSum` and the `postCount`, divided to calculate the ratio.
 * The result is sorted based on the `upvoteToPostRatio` in descending order.
 
-<!--DOCUSAURUS_CODE_TABS-->
+<Tabs>
+
+<TabItem value="5" label="cURL">
 
-<!--cURL-->
 
 ```shell
 curl "http://ROUTER_IP:ROUTER_PORT/druid/v2" \
@@ -217,7 +230,9 @@ curl "http://ROUTER_IP:ROUTER_PORT/druid/v2" \
 }'
 ```
 
-<!--HTTP-->
+</TabItem>
+
+<TabItem value="6" label="HTTP">
 
 ```HTTP
 POST /druid/v2?pretty=null HTTP/1.1
@@ -256,12 +271,14 @@ Content-Length: 817
 }
 ```
 
-<!--END_DOCUSAURUS_CODE_TABS-->
+</TabItem>
+</Tabs>
 
 #### Example response: `groupBy`
 
 <details>
   <summary>Click to show sample response</summary>
+
 ```json
 [
     {
@@ -280,7 +297,7 @@ Content-Length: 817
 
 ## Get segment information for query
 
-Retrieves an array that contains objects with segment information, including the server locations associated with the query provided in the request body. 
+Retrieves an array that contains objects with segment information, including the server locations associated with the query provided in the request body.
 
 ### URL
 
@@ -292,13 +309,16 @@ Retrieves an array that contains objects with segment information, including the
 
 ### Responses
 
-<!--DOCUSAURUS_CODE_TABS-->
+<Tabs>
+
+<TabItem value="7" label="200 SUCCESS">
+
 
-<!--200 SUCCESS-->
+*Successfully retrieved segment information*
 
-*Successfully retrieved segment information* 
+</TabItem>
+<TabItem value="8" label="400 BAD REQUEST">
 
-<!--400 BAD REQUEST-->
 
 *Error thrown due to bad query. Returns a JSON object detailing the error with the following format:*
 
@@ -312,15 +332,17 @@ Retrieves an array that contains objects with segment information, including the
 ```
 For more information on possible error messages, see [query execution failures](../querying/querying.md#query-execution-failures).
 
-<!--END_DOCUSAURUS_CODE_TABS-->
+</TabItem>
+</Tabs>
 
 ---
 
 ### Sample request
 
-<!--DOCUSAURUS_CODE_TABS-->
+<Tabs>
+
+<TabItem value="9" label="cURL">
 
-<!--cURL-->
 
 ```shell
 curl "http://ROUTER_IP:ROUTER_PORT/druid/v2/candidates" \
@@ -345,7 +367,9 @@ curl "http://ROUTER_IP:ROUTER_PORT/druid/v2/candidates" \
 }'
 ```
 
-<!--HTTP-->
+</TabItem>
+<TabItem value="10" label="HTTP">
+
 
 ```HTTP
 POST /druid/v2/candidates HTTP/1.1
@@ -374,7 +398,8 @@ Content-Length: 336
 }
 ```
 
-<!--END_DOCUSAURUS_CODE_TABS-->
+</TabItem>
+</Tabs>
 
 ### Sample response
 
@@ -895,4 +920,4 @@ Content-Length: 336
     }
 ]
   ```
-</details>
+</details>
diff --git a/docs/api-reference/legacy-metadata-api.md b/docs/api-reference/legacy-metadata-api.md
@@ -99,8 +99,10 @@ If no used segments are found for the given inputs, this API returns `204 No Con
 
 ## Metadata store information
 
-> Note: Much of this information is available in a simpler, easier-to-use form through the Druid SQL
-> [`sys.segments`](../querying/sql-metadata-tables.md#segments-table) table.
+:::info
+ Note: Much of this information is available in a simpler, easier-to-use form through the Druid SQL
+ [`sys.segments`](../querying/sql-metadata-tables.md#segments-table) table.
+:::
 
 `GET /druid/coordinator/v1/metadata/segments`
 
@@ -279,10 +281,12 @@ This section documents the API endpoints for the processes that reside on Query
 Note that all _interval_ URL parameters are ISO 8601 strings delimited by a `_` instead of a `/`
 as in `2016-06-27_2016-06-28`.
 
-> Note: Much of this information is available in a simpler, easier-to-use form through the Druid SQL
-> [`INFORMATION_SCHEMA.TABLES`](../querying/sql-metadata-tables.md#tables-table),
-> [`INFORMATION_SCHEMA.COLUMNS`](../querying/sql-metadata-tables.md#columns-table), and
-> [`sys.segments`](../querying/sql-metadata-tables.md#segments-table) tables.
+:::info
+ Note: Much of this information is available in a simpler, easier-to-use form through the Druid SQL
+ [`INFORMATION_SCHEMA.TABLES`](../querying/sql-metadata-tables.md#tables-table),
+ [`INFORMATION_SCHEMA.COLUMNS`](../querying/sql-metadata-tables.md#columns-table), and
+ [`sys.segments`](../querying/sql-metadata-tables.md#segments-table) tables.
+:::
 
 `GET /druid/v2/datasources`
 
@@ -296,17 +300,21 @@ If no interval is specified, a default interval spanning a configurable period b
 
 `GET /druid/v2/datasources/{dataSourceName}/dimensions`
 
-> This API is deprecated and will be removed in future releases. Please use [SegmentMetadataQuery](../querying/segmentmetadataquery.md) instead
-> which provides more comprehensive information and supports all dataSource types including streaming dataSources. It's also encouraged to use [INFORMATION_SCHEMA tables](../querying/sql-metadata-tables.md)
-> if you're using SQL.
-> 
+:::info
+ This API is deprecated and will be removed in future releases. Please use [SegmentMetadataQuery](../querying/segmentmetadataquery.md) instead
+ which provides more comprehensive information and supports all dataSource types including streaming dataSources. It's also encouraged to use [INFORMATION_SCHEMA tables](../querying/sql-metadata-tables.md)
+ if you're using SQL.
+:::
+
 Returns the dimensions of the datasource.
 
 `GET /druid/v2/datasources/{dataSourceName}/metrics`
 
-> This API is deprecated and will be removed in future releases. Please use [SegmentMetadataQuery](../querying/segmentmetadataquery.md) instead
-> which provides more comprehensive information and supports all dataSource types including streaming dataSources. It's also encouraged to use [INFORMATION_SCHEMA tables](../querying/sql-metadata-tables.md)
-> if you're using SQL.
+:::info
+ This API is deprecated and will be removed in future releases. Please use [SegmentMetadataQuery](../querying/segmentmetadataquery.md) instead
+ which provides more comprehensive information and supports all dataSource types including streaming dataSources. It's also encouraged to use [INFORMATION_SCHEMA tables](../querying/sql-metadata-tables.md)
+ if you're using SQL.
+:::
 
 Returns the metrics of the datasource.