Enable use of HTML in docs (#1900)

Fix alignment documentation:
- while it renders fine on the web, it's stripped from man pages.
  Inline HTML renders fine in some cases, but tables don't.

There's no unified (remark) plugin that works well with headless
tables pandoc supports as well, so the only way to achieve a similar
effect is to leave header cells empty.

Signed-off-by: Tin Švagelj <tin.svagelj@live.com>

doc/CMakeLists.txt

@@ -25,9 +25,10 @@ if(BUILD_DOCS)
         WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
         SOURCES config_settings.yaml variables.yaml lua.yaml man.md.j2
     )
+    set(pandoc_mode markdown-markdown_in_html_blocks+raw_html)
     add_custom_target(conky.1
         ALL
-        COMMAND ${APP_PANDOC} --standalone -f markdown+raw_html -t man ${CMAKE_CURRENT_BINARY_DIR}/man.md > ${CMAKE_CURRENT_BINARY_DIR}/conky.1
+        COMMAND ${APP_PANDOC} --standalone -f ${pandoc_mode} -t man ${CMAKE_CURRENT_BINARY_DIR}/man.md > ${CMAKE_CURRENT_BINARY_DIR}/conky.1
         SOURCES config_settings.yaml variables.yaml lua.yaml man.md.j2
     )
     add_dependencies(conky.1 man.md)

doc/config_settings.yaml

@@ -29,23 +29,11 @@ values:
     desc: |-
       Aligned position on screen, may be `none` or one of:
 
-       <table>
-        <tr>
-          <td><code>top_left</code> (<em>or</em> <code>tl</code>)</td>
-          <td><code>top_middle</code> (<em>or</em> <code>tm</code>)</td>
-          <td><code>top_right</code> (<em>or</em> <code>tr</code>)</td>
-        </tr>
-        <tr>
-          <td><code>middle_left</code> (<em>or</em> <code>ml</code>)</td>
-          <td><code>middle_middle</code> (<em>or</em> <code>mm</code>)</td>
-          <td><code>middle_right</code> (<em>or</em> <code>mr</code>)</td>
-        </tr>
-        <tr>
-          <td><code>bottom_left</code> (<em>or</em> <code>bl</code>)</td>
-          <td><code>bottom_middle</code> (<em>or</em> <code>bm</code>)</td>
-          <td><code>bottom_right</code> (<em>or</em> <code>br</code>)</td>
-        </tr>
-      </table>
+      |                       |                         |                        |
+      |:----------------------|:-----------------------:|-----------------------:|
+      |`top_left` (or `tl`)   | `top_middle` (or `tm`)  |   `top_right` (or `tr`)|
+      |`middle_left` (or `ml`)|`middle_middle` (or `mm`)|`middle_right` (or `mr`)|
+      |`bottom_left` (or `bl`)|`bottom_middle` (or `bm`)|`bottom_right` (or `br`)|
 
       In case of `panel` and `dock` windows, it might make more sense to use one
       of the following aliases:

web/package.json

@@ -35,9 +35,9 @@
     "gray-matter": "^4.0.3",
     "inter-ui": "^4.0.2",
     "next": "^14.1.4",
+    "react": "^18.2.0",
     "react-dom": "^18.2.0",
     "react-feather": "^2.0.10",
-    "react": "^18.2.0",
     "rehype-parse": "^9.0.0",
     "rehype-react": "^8.0.0"
   },
@@ -45,17 +45,17 @@
     "@types/eslint": "^8.56.8",
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^20.12.7",
-    "@types/react-dom": "^18.2.25",
     "@types/react": "^18.2.76",
+    "@types/react-dom": "^18.2.25",
     "@typescript-eslint/eslint-plugin": "^7.6.0",
     "@typescript-eslint/parser": "^7.6.0",
     "autoprefixer": "^10.4.19",
     "cypress": "^13.7.2",
+    "eslint": "^8.57.0",
     "eslint-config-next": "^14.1.4",
     "eslint-config-prettier": "^9.1.0",
     "eslint-plugin-cypress": "^2.15.1",
     "eslint-plugin-mdx": "^3.1.5",
-    "eslint": "^8.57.0",
     "js-yaml": "^4.1.0",
     "netlify-cli": "^17.22.1",
     "netlify-plugin-cypress": "^2.2.1",

web/utils/doc-utils.ts

@@ -66,8 +66,8 @@ function processMarkdown(input: string): string {
   return unified()
     .use(remarkParse)
     .use(remarkGfm)
-    .use(remarkRehype)
-    .use(rehypeStringify)
+    .use(remarkRehype, {allowDangerousHtml: true})
+    .use(rehypeStringify, {allowDangerousHtml: true})
     .processSync(input)
     .toString()
 }

web/utils/mdx-utils.ts

@@ -62,9 +62,9 @@ export const getDocumentBySlug = async (slug: string) => {
   const result = await unified()
     .use(remarkParse)
     .use(remarkGfm)
-    .use(remarkRehype)
+    .use(remarkRehype, {allowDangerousHtml: true})
     // .use(rehypePrism)
-    .use(rehypeStringify)
+    .use(rehypeStringify, {allowDangerousHtml: true})
     .process(content)
 
   return { source: result.value, data, documentFilePath }