Some docs optimization (#6890)

* some markdown docs optimization

* markdown escape

docs/content/development/extensions-core/kafka-ingestion.md

@@ -140,7 +140,7 @@ The tuningConfig is optional and default parameters will be used if no tuningCon
 |`intermediatePersistPeriod`|ISO8601 Period|The period that determines the rate at which intermediate persists occur.|no (default == PT10M)|
 |`maxPendingPersists`|Integer|Maximum number of persists that can be pending but not started. If this limit would be exceeded by a new intermediate persist, ingestion will block until the currently-running persist finishes. Maximum heap memory usage for indexing scales with maxRowsInMemory * (2 + maxPendingPersists).|no (default == 0, meaning one persist can be running concurrently with ingestion, and none can be queued up)|
 |`indexSpec`|Object|Tune how data is indexed, see 'IndexSpec' below for more details.|no|
-|`reportParseExceptions`|DEPRECATED. If true, exceptions encountered during parsing will be thrown and will halt ingestion; if false, unparseable rows and fields will be skipped. Setting `reportParseExceptions` to true will override existing configurations for `maxParseExceptions` and `maxSavedParseExceptions`, setting `maxParseExceptions` to 0 and limiting `maxSavedParseExceptions` to no more than 1.|false|no|
+|`reportParseExceptions`|Boolean|*DEPRECATED*. If true, exceptions encountered during parsing will be thrown and will halt ingestion; if false, unparseable rows and fields will be skipped. Setting `reportParseExceptions` to true will override existing configurations for `maxParseExceptions` and `maxSavedParseExceptions`, setting `maxParseExceptions` to 0 and limiting `maxSavedParseExceptions` to no more than 1.|no (default == false)|
 |`handoffConditionTimeout`|Long|Milliseconds to wait for segment handoff. It must be >= 0, where 0 means to wait forever.|no (default == 0)|
 |`resetOffsetAutomatically`|Boolean|Whether to reset the consumer offset if the next offset that it is trying to fetch is less than the earliest available offset for that particular partition. The consumer offset will be reset to either the earliest or latest offset depending on `useEarliestOffset` property of `KafkaSupervisorIOConfig` (see below). This situation typically occurs when messages in Kafka are no longer available for consumption and therefore won't be ingested into Druid. If set to false then ingestion for that particular partition will halt and manual intervention is required to correct the situation, please see `Reset Supervisor` API below.|no (default == false)|
 |`workerThreads`|Integer|The number of threads that will be used by the supervisor for asynchronous operations.|no (default == min(10, taskCount))|

docs/content/ingestion/ingestion-spec.md

@@ -207,7 +207,7 @@ handle all formatting decisions on their own, without using the ParseSpec.
 | Field | Type | Description | Required |
 |-------|------|-------------|----------|
 | column | String | The column of the timestamp. | yes |
-| format | String | iso, posix, millis, micro, nano, auto or any [Joda time](http://joda-time.sourceforge.net/apidocs/org/joda/time/format/DateTimeFormat.html) format. | no (default == 'auto' |
+| format | String | iso, posix, millis, micro, nano, auto or any [Joda time](http://joda-time.sourceforge.net/apidocs/org/joda/time/format/DateTimeFormat.html) format. | no (default == 'auto') |
 
 <a name="dimensions" />
 
@@ -216,8 +216,8 @@ handle all formatting decisions on their own, without using the ParseSpec.
 | Field | Type | Description | Required |
 |-------|------|-------------|----------|
 | dimensions | JSON array | A list of [dimension schema](#dimension-schema) objects or dimension names. Providing a name is equivalent to providing a String-typed dimension schema with the given name. If this is an empty array, Druid will treat all non-timestamp, non-metric columns that do not appear in "dimensionExclusions" as String-typed dimension columns. | yes |
-| dimensionExclusions | JSON String array | The names of dimensions to exclude from ingestion. | no (default == [] |
-| spatialDimensions | JSON Object array | An array of [spatial dimensions](../development/geo.html) | no (default == [] |
+| dimensionExclusions | JSON String array | The names of dimensions to exclude from ingestion. | no (default == []) |
+| spatialDimensions | JSON Object array | An array of [spatial dimensions](../development/geo.html) | no (default == []) |
 
 #### Dimension Schema
 A dimension schema specifies the type and name of a dimension to be ingested.

docs/content/operations/api-reference.md

@@ -151,7 +151,7 @@ Returns a list of all segments, overlapping with any of given intervals, for a d
 
 #### Datasources
 
-Note that all _interval_ URL parameters are ISO 8601 strings delimited by a `_` instead of a `/` 
+Note that all _interval_ URL parameters are ISO 8601 strings delimited by a `_` instead of a `/`
 (e.g., 2016-06-27_2016-06-28).
 
 ##### GET
@@ -247,7 +247,7 @@ Disables a segment.
 
 #### Retention Rules
 
-Note that all _interval_ URL parameters are ISO 8601 strings delimited by a `_` instead of a `/` 
+Note that all _interval_ URL parameters are ISO 8601 strings delimited by a `_` instead of a `/`
 (e.g., 2016-06-27_2016-06-28).
 
 ##### GET
@@ -296,7 +296,7 @@ Optional Header Parameters for auditing the config change can also be specified.
 
 #### Intervals
 
-Note that all _interval_ URL parameters are ISO 8601 strings delimited by a `_` instead of a `/` 
+Note that all _interval_ URL parameters are ISO 8601 strings delimited by a `_` instead of a `/`
 (e.g., 2016-06-27_2016-06-28).
 
 ##### GET
@@ -389,7 +389,7 @@ only want the active leader to be considered in-service at the load balancer.
 
 #### Tasks<a name="overlord-tasks"></a> 
 
-Note that all _interval_ URL parameters are ISO 8601 strings delimited by a `_` instead of a `/` 
+Note that all _interval_ URL parameters are ISO 8601 strings delimited by a `_` instead of a `/`
 (e.g., 2016-06-27_2016-06-28).
 
 ##### GET
@@ -402,7 +402,7 @@ Retrieve list of tasks. Accepts query string parameters `state`, `datasource`, `
 |---|---|
 |`state`|filter list of tasks by task state, valid options are `running`, `complete`, `waiting`, and `pending`.|
 | `datasource`| return tasks filtered by Druid datasource.|
-| `createdTimeInterval`| return tasks created within the specified interval. | 
+| `createdTimeInterval`| return tasks created within the specified interval. |
 | `max`| maximum number of `"complete"` tasks to return. Only applies when `state` is set to `"complete"`.|
 | `type`| filter tasks by task type. See [task documentation](../ingestion/tasks.html) for more details.|
 
@@ -465,8 +465,8 @@ Retrieve list of task status objects for list of task id strings in request body
 
 * `/druid/indexer/v1/pendingSegments/{dataSource}`
 
-Manually clean up pending segments table in metadata storage for `datasource`. Returns a JSON object response with 
-`numDeleted` and count of rows deleted from the pending segments table. This API is used by the 
+Manually clean up pending segments table in metadata storage for `datasource`. Returns a JSON object response with
+`numDeleted` and count of rows deleted from the pending segments table. This API is used by the
 `druid.coordinator.kill.pendingSegments.on` [coordinator setting](../configuration/index.html#coordinator-operation)
 which automates this operation to perform periodically.
 
@@ -547,20 +547,20 @@ Please use the equivalent 'terminate' instead.
 </div>
 
 #### Dynamic Configuration
-See [Overlord Dynamic Configuration](../configuration/index.html#overlord-dynamic-configuration) for details. 
+See [Overlord Dynamic Configuration](../configuration/index.html#overlord-dynamic-configuration) for details.
 
-Note that all _interval_ URL parameters are ISO 8601 strings delimited by a `_` instead of a `/` 
+Note that all _interval_ URL parameters are ISO 8601 strings delimited by a `_` instead of a `/`
 (e.g., 2016-06-27_2016-06-28).
 
 ##### GET
 
 * `/druid/indexer/v1/worker`
 
-Retreives current overlord dynamic configuration. 
+Retreives current overlord dynamic configuration.
 
 * `/druid/indexer/v1/worker/history?interval={interval}&counter={count}`
 
-Retrieves history of changes to overlord dynamic configuration. Accepts `interval` and  `count` query string parameters 
+Retrieves history of changes to overlord dynamic configuration. Accepts `interval` and  `count` query string parameters
 to filter by interval and limit the number of results respectively.
 
 * `/druid/indexer/v1/scaling`
@@ -575,7 +575,7 @@ Update overlord dynamic worker configuration.
 
 ## Data Server
 
-This section documents the API endpoints for the processes that reside on Data servers (MiddleManagers/Peons and Historicals) 
+This section documents the API endpoints for the processes that reside on Data servers (MiddleManagers/Peons and Historicals)
 in the suggested [three-server configuration](../design/processes.html#server-types).
 
 ### MiddleManager
@@ -584,7 +584,7 @@ in the suggested [three-server configuration](../design/processes.html#server-ty
 
 * `/druid/worker/v1/enabled`
 
-Check whether a MiddleManager is in an enabled or disabled state. Returns JSON object keyed by the combined `druid.host` 
+Check whether a MiddleManager is in an enabled or disabled state. Returns JSON object keyed by the combined `druid.host`
 and `druid.port` with the boolean state as the value.
 
 ```json
@@ -593,14 +593,14 @@ and `druid.port` with the boolean state as the value.
 
 * `/druid/worker/v1/tasks`
 
-Retrieve a list of active tasks being run on MiddleManager. Returns JSON list of taskid strings.  Normal usage should 
+Retrieve a list of active tasks being run on MiddleManager. Returns JSON list of taskid strings.  Normal usage should
 prefer to use the `/druid/indexer/v1/tasks` [Overlord API](#overlord) or one of it's task state specific variants instead.
 
 ```json
 ["index_wikiticker_2019-02-11T02:20:15.316Z"]
 ```
 
-* `/druid/worker/v1/task/{taskid}/log` 
+* `/druid/worker/v1/task/{taskid}/log`
 
 Retrieve task log output stream by task id. Normal usage should prefer to use the `/druid/indexer/v1/task/{taskId}/log`
 [Overlord API](#overlord) instead.
@@ -609,7 +609,7 @@ Retrieve task log output stream by task id. Normal usage should prefer to use th
 
 * `/druid/worker/v1/disable`
 
-'Disable' a MiddleManager, causing it to stop accepting new tasks but complete all existing tasks. Returns JSON  object 
+'Disable' a MiddleManager, causing it to stop accepting new tasks but complete all existing tasks. Returns JSON  object
 keyed by the combined `druid.host` and `druid.port`:
 
 ```json
@@ -618,7 +618,7 @@ keyed by the combined `druid.host` and `druid.port`:
 
 * `/druid/worker/v1/enable`
 
-'Enable' a MiddleManager, allowing it to accept new tasks again if it was previously disabled. Returns JSON  object 
+'Enable' a MiddleManager, allowing it to accept new tasks again if it was previously disabled. Returns JSON  object
 keyed by the combined `druid.host` and `druid.port`:
 
 ```json
@@ -627,7 +627,7 @@ keyed by the combined `druid.host` and `druid.port`:
 
 * `/druid/worker/v1/task/{taskid}/shutdown`
 
-Shutdown a running task by `taskid`. Normal usage should prefer to use the `/druid/indexer/v1/task/{taskId}/shutdown` 
+Shutdown a running task by `taskid`. Normal usage should prefer to use the `/druid/indexer/v1/task/{taskId}/shutdown`
 [Overlord API](#overlord) instead. Returns JSON:
 
 ```json
@@ -673,7 +673,7 @@ This section documents the API endpoints for the processes that reside on Query
 
 #### Datasource Information
 
-Note that all _interval_ URL parameters are ISO 8601 strings delimited by a `_` instead of a `/` 
+Note that all _interval_ URL parameters are ISO 8601 strings delimited by a `_` instead of a `/`
 (e.g., 2016-06-27_2016-06-28).
 
 ##### GET
@@ -695,8 +695,8 @@ druid.query.segmentMetadata.defaultHistory
 Returns the dimensions of the datasource.
 
 <div class="note caution">
-This API is deprecated and will be removed in future releases. Please use <a href="../querying/segmentmetadataquery.html">SegmentMetadataQuery</a> 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.html#retrieving-metadata)
+This API is deprecated and will be removed in future releases. Please use <a href="/querying/segmentmetadataquery.html">SegmentMetadataQuery</a> instead
+which provides more comprehensive information and supports all dataSource types including streaming dataSources. It's also encouraged to use <a href="/querying/sql.html#retrieving-metadata">INFORMATION_SCHEMA tables</a>
 if you're using SQL.
 </div>
 

docs/content/querying/sql.md

@@ -171,7 +171,7 @@ String functions accept strings, and return a type appropriate to the function.
 
 |Function|Notes|
 |--------|-----|
-|`x \|\| y`|Concat strings x and y.|
+|`<code>x &#124;&#124; y</code>`|Concat strings x and y.|
 |`CONCAT(expr, expr...)`|Concats a list of expressions.|
 |`TEXTCAT(expr, expr)`|Two argument version of CONCAT.|
 |`STRING_FORMAT(pattern[, args...])`|Returns a string formatted in the manner of Java's [String.format](https://docs.oracle.com/javase/8/docs/api/java/lang/String.html#format-java.lang.String-java.lang.Object...-).|
@@ -190,7 +190,7 @@ String functions accept strings, and return a type appropriate to the function.
 |`RIGHT(expr, [length])`|Returns the rightmost length characters from expr.|
 |`LEFT(expr, [length])`|Returns the leftmost length characters from expr.|
 |`SUBSTR(expr, index, [length])`|Synonym for SUBSTRING.|
-|`TRIM([BOTH \| LEADING \| TRAILING] [<chars> FROM] expr)`|Returns expr with characters removed from the leading, trailing, or both ends of "expr" if they are in "chars". If "chars" is not provided, it defaults to " " (a space). If the directional argument is not provided, it defaults to "BOTH".|
+|`TRIM([BOTH &#124; LEADING &#124; TRAILING] [<chars> FROM] expr)`|Returns expr with characters removed from the leading, trailing, or both ends of "expr" if they are in "chars". If "chars" is not provided, it defaults to " " (a space). If the directional argument is not provided, it defaults to "BOTH".|
 |`BTRIM(expr[, chars])`|Alternate form of `TRIM(BOTH <chars> FROM <expr>`).|
 |`LTRIM(expr[, chars])`|Alternate form of `TRIM(LEADING <chars> FROM <expr>`).|
 |`RTRIM(expr[, chars])`|Alternate form of `TRIM(TRAILING <chars> FROM <expr>`).|
@@ -224,7 +224,7 @@ over the connection time zone.
 |`FLOOR(timestamp_expr TO <unit>)`|Rounds down a timestamp, returning it as a new timestamp. Unit can be SECOND, MINUTE, HOUR, DAY, WEEK, MONTH, QUARTER, or YEAR.|
 |`CEIL(timestamp_expr TO <unit>)`|Rounds up a timestamp, returning it as a new timestamp. Unit can be SECOND, MINUTE, HOUR, DAY, WEEK, MONTH, QUARTER, or YEAR.|
 |`TIMESTAMPADD(<unit>, <count>, <timestamp>)`|Equivalent to `timestamp + count * INTERVAL '1' UNIT`.|
-|`timestamp_expr { + \| - } <interval_expr>`|Add or subtract an amount of time from a timestamp. interval_expr can include interval literals like `INTERVAL '2' HOUR`, and may include interval arithmetic as well. This operator treats days as uniformly 86400 seconds long, and does not take into account daylight savings time. To account for daylight savings time, use TIME_SHIFT instead.|
+|`timestamp_expr { + &#124; - } <interval_expr>`|Add or subtract an amount of time from a timestamp. interval_expr can include interval literals like `INTERVAL '2' HOUR`, and may include interval arithmetic as well. This operator treats days as uniformly 86400 seconds long, and does not take into account daylight savings time. To account for daylight savings time, use TIME_SHIFT instead.|
 
 ### Comparison operators