From 78651157d77403332a6afa052fe785e76afc687b Mon Sep 17 00:00:00 2001 From: DanRoscigno Date: Tue, 6 Jun 2023 14:23:52 -0400 Subject: [PATCH] add my notes and update spell --- ClickHouse-specific.md | 52 +++++++++++++++++++++++ my-docs-.ignore-file-for-marksman | 19 +++++++++ my-docs-.marksman.toml-file-for-marksman | 9 ++++ spell/en.utf-8.add | 2 + spell/en.utf-8.add.spl | Bin 3699 -> 3723 bytes 5 files changed, 82 insertions(+) create mode 100644 ClickHouse-specific.md create mode 100644 my-docs-.ignore-file-for-marksman create mode 100644 my-docs-.marksman.toml-file-for-marksman diff --git a/ClickHouse-specific.md b/ClickHouse-specific.md new file mode 100644 index 00000000..41547def --- /dev/null +++ b/ClickHouse-specific.md @@ -0,0 +1,52 @@ +## Working with Marksman and multiple repos + +In order to keep the docs close to the source-code at ClickHouse +most of the reference (SQL syntax, etc.) docs are in the repo +where the code is. This gives us heartburn when building the +docs with Docusaurus as the files need to be combined. In the +`.gitignore` file for the docs repo all of the dirs copied over +from the ClickHouse repo are marked to be ignored; this causes the +wonderful Marksman LSP to ignore the reference docs, and marks +any links to the reference docs invalid. + +The Marksman author came up with a great workaround, as `.ignore` gets +processed after `.gitignore`, I negate the ignore in `.ignore` and +the reference docs are now eligible for linking. +``` +# This is to reverse the .gitignore in the ClickHouse-docs repo, as +# the marksman LSP ignores dirs in the .gitignore when checking +# for links for markdown files. This file (.ignore) gets processed +# after .gitignore, so the negation (`!`) of the path fixes the issue +# created by copying the files into the clickhouse-docs directory +# structure + +# place at root dir of the markdown project, for example: +# $GITHUB/clickhouse-docs/.ignore + +!docs/en/development +!docs/en/engines +!docs/en/getting-started +!docs/en/interfaces +!docs/en/operations +!docs/en/sql-reference +docs/ru +docs/zh +docs/_clients +``` + +## Configuring Marksman + +Maybe not needed, but I am not sure. I think that `.mdx` files +may now be considered Markdown, I should check. I don't like table of +contents to be created, so this is disabled. + +``` +# Place at root directory of the markdown project, for example: +# $GITHUB/clickhouse-docs/.marksman.toml +[core] +markdown.file_extensions = ["md", "mdx"] +text_sync = "full" + +[code_action] +toc.enable = false # Enable/disable "Table of Contents" code action +``` diff --git a/my-docs-.ignore-file-for-marksman b/my-docs-.ignore-file-for-marksman new file mode 100644 index 00000000..b458cb10 --- /dev/null +++ b/my-docs-.ignore-file-for-marksman @@ -0,0 +1,19 @@ +# This is to reverse the .gitignore in the ClickHouse-docs repo, as +# the marksman LSP ignores dirs in the .gitignore when checking +# for links for markdown files. This file (.ignore) gets processed +# after .gitignore, so the negation (`!`) of the path fixes the issue +# created by copying the files into the clickhouse-docs directory +# structure + +# place at root dir of the markdown project, for example: +# $GITHUB/clickhouse-docs/.ignore + +!docs/en/development +!docs/en/engines +!docs/en/getting-started +!docs/en/interfaces +!docs/en/operations +!docs/en/sql-reference +docs/ru +docs/zh +docs/_clients diff --git a/my-docs-.marksman.toml-file-for-marksman b/my-docs-.marksman.toml-file-for-marksman new file mode 100644 index 00000000..c62376bc --- /dev/null +++ b/my-docs-.marksman.toml-file-for-marksman @@ -0,0 +1,9 @@ +# place at root dir of the markdown project, for example: +# $GITHUB/clickhouse-docs/.marksman.toml +[core] +markdown.file_extensions = ["md", "mdx"] +text_sync = "full" + +[code_action] +toc.enable = false # Enable/disable "Table of Contents" code action + diff --git a/spell/en.utf-8.add b/spell/en.utf-8.add index 2eb29d52..2ee5fc28 100644 --- a/spell/en.utf-8.add +++ b/spell/en.utf-8.add @@ -222,3 +222,5 @@ chnode2 chnode3 marsnet uuid +Docusaurus +LSP diff --git a/spell/en.utf-8.add.spl b/spell/en.utf-8.add.spl index 1a53e92fb2cedf53c8ac2e5702776012e799f05f..373ccaec0c61e0e56f94778978f7c5f400aa2308 100644 GIT binary patch delta 458 zcmX9)JxIeq6ux)8CJjg@5v5kpVxf!0nxzhc9h450PHuv+2{o8Dp=YtWl{yGIC~t8T z#KBQI2wDgZN?lx>9Cg+~1V{B<9q!}!?)!Q7zQzxe@zr8U29D?Dei_qVui~8JFuxz; z6<{nQp$QT!!Ui2;I6O&2_FxlrK_8H#Si@*Bj9&{Jh=>PJ;NEeOaRU9kwtc%he}f!}(8M+}^g zwIRe_EIabv;PlRxYgFjd)ILST&ndr^dB370WU(O0H$4I!B`qSa0ZKM=4f8E T9M)F-B7tYdB7An=j1%z(;E`!{ delta 371 zcmW-dF-yZh6vy*kFS%wZA}CbbQW13!EYwMaq7F*If|TMQ3Puw&7)@weh=PMSI>}qQ zIw^=0DN?a?^aBW;g?<2CTtozY*Wr%4|NGsK_wFkFl}cdSY&@?ZO^7P-Vt}8WXXKBQ4u; zeM;*|X{k4zfEM)#!y0w;UD&3SF#+dPFiPoRA1nyjeZ(9-x$I!R9w|?j?u@+5*dA9t zsBcU{mvlJ=Wtx>)XwtfzFNoh4v;##~T=39xVILhf6y2ERS2-6=PZ@VqcL%&82oN;A zVDYv@UAX~!l!&h&ep5Mq!PZ_pH~L;hu4`+@JeJR`sgJ-mCC%yah8or3rfmoYxo9c^ aG~<@G%vFf!#vH-e13jC|&~N>i*Ww=?Vp|6Q