From 1dc2761359ead463659fc577ead48542a76400c9 Mon Sep 17 00:00:00 2001 From: axemonk Date: Sat, 15 Feb 2025 15:08:37 -0600 Subject: [PATCH 1/6] Add completions metadata section (#121) Remove redundant info. Add short description and example re `annotations` Added completions metadata section --- docs/reference/completions.md | 40 +++++++++++++++++++++++++++++------ 1 file changed, 33 insertions(+), 7 deletions(-) diff --git a/docs/reference/completions.md b/docs/reference/completions.md index 8d1fa69c..fe65d260 100644 --- a/docs/reference/completions.md +++ b/docs/reference/completions.md @@ -79,7 +79,6 @@ is identical to the `contents`: ```json { "trigger": "foo", "contents": "foobar" }, -{ "trigger": "foo\ttest", "contents": "foobar" } ``` **trigger** @@ -87,12 +86,6 @@ is identical to the `contents`: and will cause the `contents` to be inserted when chosen. - You can use a `\t` tab character - to add an *annotation* for the preceding trigger. - The annotation will be displayed right-aligned, - slightly grayed - and does not affect the trigger itself. - **contents** : Text to be inserted in the buffer. Supports the same string interpolation features @@ -108,3 +101,36 @@ you have to escape it like this: `\\$` (double backslashes are needed because we are within a JSON string). ::: + + +## Completions Metadata + +``` json +{ + "trigger": "func", + "contents": "funcbar", + "annotation": "string", + "kind": "function", + "details": "A short description of what this string function does." +} + +{ "trigger": "func\tstring", "contents": "funcbar" } +``` + +::: info Added in build 4050. + These do not affect the triggers themselves, + but allow for customization of the appearance of completions in the completions list. +::: + +**kind** +: Allows for categorization of the completion via a colored + kind letter to the left of the entry in the completions list. + Colors are determined by the user's color scheme. + +**annotation** +: Displays as right-aligned gray text to the right of the entry in the completions list. + Does not affect the trigger itself. + Annotations can also be defined using a tab character `\t` in `trigger`. + +**details** +: Displays at the bottom of the completions list when the entry is highlighted. From eb2d1ebbf5c433a555841c1020aa552bcb21e7b8 Mon Sep 17 00:00:00 2001 From: FichteFoll Date: Sun, 16 Feb 2025 16:50:02 +0100 Subject: [PATCH 2/6] Add custom "added" blocks --- CONTRIBUTING.md | 21 +++++++++++++ docs/.vitepress/config.ts | 2 ++ docs/.vitepress/theme/custom.css | 9 ++++++ package.json | 1 + pnpm-lock.yaml | 54 ++++++++++++++++++++++++++++++++ 5 files changed, 87 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8b3327b5..793ec62d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -204,6 +204,27 @@ With text ### This SHOULD NOT be a h4 ``` + +### Custom blocks + +A custom block feature is provided +by the [vitepress default theme][vp-default]. +Supported block types are +`tip`, +`warning`, +`danger`, +and `details`. + +Additionally, special CSS is provided +for a custom block using [markdown-it-attrs][] +to mark when a certain feature was added: + +``` +::: tip Added in build 4050 {added} +::: +``` + + ### File Paths File paths (relative or absolute) diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index 4d90b903..f464e110 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -1,3 +1,4 @@ +import markdownItAttrs from 'markdown-it-attrs'; import markdownItDeflist from 'markdown-it-deflist'; import markdownItFootnote from 'markdown-it-footnote'; import { defineConfig, type HeadConfig } from 'vitepress'; @@ -188,6 +189,7 @@ export default defineConfig({ theme: 'material-theme-palenight', lineNumbers: true, config: md => { + md.use(markdownItAttrs); md.use(markdownItDeflist); md.use(markdownItFootnote); }, diff --git a/docs/.vitepress/theme/custom.css b/docs/.vitepress/theme/custom.css index 232e81a2..f0fa3297 100644 --- a/docs/.vitepress/theme/custom.css +++ b/docs/.vitepress/theme/custom.css @@ -24,6 +24,7 @@ --vp-home-hero-name-color: var(--vp-c-brand); --vp-button-brand-bg: var(--vp-c-brand); + --vp-custom-block-added-bg: hsl(90, 55%, 87%); --vp-custom-block-tip-bg: rgb(204 204 204 / 16%); --vp-c-divider: var(--vp-c-bg-soft); @@ -36,6 +37,7 @@ --vp-c-bg-soft: hsl(215, 17%, 16%); --docsearch-container-background: hsla(0,0%,40%,0.3); + --vp-custom-block-added-bg: hsl(90, 14%, 27%); } @@ -76,3 +78,10 @@ a.term { a.term:hover { border-color: var(--vp-c-brand-2); } + +/* "Added in build" */ +.tip.custom-block[added] { + /* Specify symmetric padding since we only use the heading. */ + padding: 8px 16px; + background-color: var(--vp-custom-block-added-bg); +} diff --git a/package.json b/package.json index 3b5ad251..cc626ada 100644 --- a/package.json +++ b/package.json @@ -12,6 +12,7 @@ "author": "", "license": "CC BY-SA 3.0 Deed", "dependencies": { + "markdown-it-attrs": "^4.3.1", "markdown-it-deflist": "^3.0.0", "markdown-it-footnote": "^4.0.0", "vitepress": "1.6.3", diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 5e36e29d..ca905ca8 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -8,6 +8,9 @@ importers: .: dependencies: + markdown-it-attrs: + specifier: ^4.3.1 + version: 4.3.1(markdown-it@14.1.0) markdown-it-deflist: specifier: ^3.0.0 version: 3.0.0 @@ -718,6 +721,9 @@ packages: resolution: {integrity: sha512-8evxG++iWyWnhng3g5RP+kwn6j+2vKLfew8pVoekn87FcfsDm92zJXKwSrU6pl+m5eAbGFhFF/gCYEQiRdbPlA==} engines: {node: '>= 14.0.0'} + argparse@2.0.1: + resolution: {integrity: sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==} + atob@2.1.2: resolution: {integrity: sha512-Wm6ukoaOGJi/73p/cl2GvLjTI5JM1k/O14isD73YML8StrH/7/lRFgmg8nICZgD3bZZvjwCGxtMOD3wWNAu8cg==} engines: {node: '>= 4.5.0'} @@ -965,6 +971,9 @@ packages: kolorist@1.8.0: resolution: {integrity: sha512-Y+60/zizpJ3HRH8DCss+q95yr6145JXZo46OTpFvDZWLfRCE4qChOyk1b26nMaNpfHHgxagk9dXT5OP0Tfe+dQ==} + linkify-it@5.0.0: + resolution: {integrity: sha512-5aHCbzQRADcdP+ATqnDuhhJ/MRIqDkZX5pyjFHRRysS8vZ5AbqGEoFIb6pYHPZ+L/OC2Lc+xT8uHVVR5CAK/wQ==} + lru-cache@5.1.1: resolution: {integrity: sha512-KpNARQA3Iwv+jTA0utUVVbrh+Jlrr1Fv0e56GGzAFOXN7dk/FviaDW8LHmK52DlcH4WP2n6gI8vN1aesBFgo9w==} @@ -974,15 +983,28 @@ packages: mark.js@8.11.1: resolution: {integrity: sha512-1I+1qpDt4idfgLQG+BNWmrqku+7/2bi5nLf4YwF8y8zXvmfiTBY3PV3ZibfrjBueCByROpuBjLLFCajqkgYoLQ==} + markdown-it-attrs@4.3.1: + resolution: {integrity: sha512-/ko6cba+H6gdZ0DOw7BbNMZtfuJTRp9g/IrGIuz8lYc/EfnmWRpaR3CFPnNbVz0LDvF8Gf1hFGPqrQqq7De0rg==} + engines: {node: '>=6'} + peerDependencies: + markdown-it: '>= 9.0.0' + markdown-it-deflist@3.0.0: resolution: {integrity: sha512-OxPmQ/keJZwbubjiQWOvKLHwpV2wZ5I3Smc81OjhwbfJsjdRrvD5aLTQxmZzzePeO0kbGzAo3Krk4QLgA8PWLg==} markdown-it-footnote@4.0.0: resolution: {integrity: sha512-WYJ7urf+khJYl3DqofQpYfEYkZKbmXmwxQV8c8mO/hGIhgZ1wOe7R4HLFNwqx7TjILbnC98fuyeSsin19JdFcQ==} + markdown-it@14.1.0: + resolution: {integrity: sha512-a54IwgWPaeBCAAsv13YgmALOF1elABB08FxO9i+r4VFk5Vl4pKokRPeX8u5TCgSsPi6ec1otfLjdOpVcgbpshg==} + hasBin: true + mdast-util-to-hast@13.2.0: resolution: {integrity: sha512-QGYKEuUsYT9ykKBCMOEDLsU5JRObWQusAolFMeko/tYPufNkRffBAQjIE+99jbA87xv6FgmjLtwjh9wBWajwAA==} + mdurl@2.0.0: + resolution: {integrity: sha512-Lf+9+2r+Tdp5wXDXC4PcIBjTDtq4UKjCPMQhKIuzpJNW0b96kVqSwW0bT7FhRSfmAiFYgP+SCRvdrDozfh0U5w==} + micromark-util-character@2.1.1: resolution: {integrity: sha512-wv8tdUTJ3thSFFFJKtpYKOYiGP2+v96Hvk4Tu8KpCAsTMs6yi+nVmGh1syvSCsaxz45J6Jbw+9DD6g97+NV67Q==} @@ -1095,6 +1117,10 @@ packages: property-information@6.5.0: resolution: {integrity: sha512-PgTgs/BlvHxOu8QuEN7wi5A0OmXaBcHpmCSTehcs6Uuu9IkDIEo13Hy7n898RHfrQ49vKCoGeWZSaAK01nwVig==} + punycode.js@2.3.1: + resolution: {integrity: sha512-uxFIHU0YlHYhDQtV4R9J6a52SLx28BCjT+4ieh7IGbgwVJWO+km431c4yRlREUAsAmt/uMjQUyQHNEPf0M39CA==} + engines: {node: '>=6'} + regex-recursion@6.0.2: resolution: {integrity: sha512-0YCaSCq2VRIebiaUviZNs0cBz1kg5kVS2UKUfNIx8YVs1cN3AV7NTctO5FOKBA+UT2BPJIWZauYHPqJODG50cg==} @@ -1207,6 +1233,9 @@ packages: trim-lines@3.0.1: resolution: {integrity: sha512-kRj8B+YHZCc9kQYdWfJB2/oUl9rA99qbowYYBtr4ui4mZyAQ2JpvVBd/6U2YloATfqBhBTSMhTpgBHtU0Mf3Rg==} + uc.micro@2.1.0: + resolution: {integrity: sha512-ARDJmphmdvUk6Glw7y9DQ2bFkKBHwQHLi2lsaH6PPmz/Ka9sFOBsBluozhDltWmnv9u/cF6Rt87znRTPV+yp/A==} + undici-types@6.19.8: resolution: {integrity: sha512-ve2KP6f/JnbPBFyobGHuerC9g1FYGn/F8n1LWTwNxCEzd6IfqTwUQcNXgEtmmQ6DlRrC1hrSrBnCZPokRrDHjw==} @@ -2066,6 +2095,8 @@ snapshots: '@algolia/requester-fetch': 5.20.2 '@algolia/requester-node-http': 5.20.2 + argparse@2.0.1: {} + atob@2.1.2: optional: true @@ -2321,6 +2352,10 @@ snapshots: kolorist@1.8.0: {} + linkify-it@5.0.0: + dependencies: + uc.micro: 2.1.0 + lru-cache@5.1.1: dependencies: yallist: 3.1.1 @@ -2331,10 +2366,23 @@ snapshots: mark.js@8.11.1: {} + markdown-it-attrs@4.3.1(markdown-it@14.1.0): + dependencies: + markdown-it: 14.1.0 + markdown-it-deflist@3.0.0: {} markdown-it-footnote@4.0.0: {} + markdown-it@14.1.0: + dependencies: + argparse: 2.0.1 + entities: 4.5.0 + linkify-it: 5.0.0 + mdurl: 2.0.0 + punycode.js: 2.3.1 + uc.micro: 2.1.0 + mdast-util-to-hast@13.2.0: dependencies: '@types/hast': 3.0.4 @@ -2347,6 +2395,8 @@ snapshots: unist-util-visit: 5.0.0 vfile: 6.0.3 + mdurl@2.0.0: {} + micromark-util-character@2.1.1: dependencies: micromark-util-symbol: 2.0.1 @@ -2446,6 +2496,8 @@ snapshots: property-information@6.5.0: {} + punycode.js@2.3.1: {} + regex-recursion@6.0.2: dependencies: regex-utilities: 2.3.0 @@ -2580,6 +2632,8 @@ snapshots: trim-lines@3.0.1: {} + uc.micro@2.1.0: {} + undici-types@6.19.8: {} unicorn-magic@0.3.0: {} From f699f5756e43d37b979b3a9430760673042e78fd Mon Sep 17 00:00:00 2001 From: FichteFoll Date: Sun, 16 Feb 2025 16:50:29 +0100 Subject: [PATCH 3/6] Mention footnotes in CONTRIBUTING.md --- CONTRIBUTING.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 793ec62d..11fac7c1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -164,6 +164,22 @@ If the relative URL is short, you MAY directly specify the target URL in text. +### Footnotes + +Footnotes are supported +using a plugin +and use a similar syntax to hyperlinks. +The link definition +is treated as the footnote's content. +It is thus also subject to Markdown parsing itself. + +```md +I am text with a footnote[^1]. + +[^1]: This footnote can use **Markdown**, such as [hyperlinks](#). +``` + + ### Headings The page's title is specified in YAML front matter From c46650e4b4784c2b20d2d5eff24020008d65b02e Mon Sep 17 00:00:00 2001 From: FichteFoll Date: Sun, 16 Feb 2025 16:50:34 +0100 Subject: [PATCH 4/6] Cleanups --- CONTRIBUTING.md | 2 +- docs/.vitepress/theme/custom.css | 3 ++- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 11fac7c1..36ee97c9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -155,7 +155,7 @@ can be found [on Wikipedia][wiki-text]. [wiki-text]: https://en.wikipedia.org/wiki/Text ``` -For relative links, +For internal links, follow the Vitepress recommendation of referencing the files with their `.md` extensions. Use absolute paths when linking diff --git a/docs/.vitepress/theme/custom.css b/docs/.vitepress/theme/custom.css index f0fa3297..104be99b 100644 --- a/docs/.vitepress/theme/custom.css +++ b/docs/.vitepress/theme/custom.css @@ -45,10 +45,11 @@ border-bottom-color: transparent !important; } -.VPNavBar.top #local-search>button { +.VPNavBar.top #local-search > button { background-color: var(--vp-c-bg-elv); } + /* Custom Style */ kbd { display: inline-block; From e1bf210e7e6aab6289745165c9844be65882f2cd Mon Sep 17 00:00:00 2001 From: FichteFoll Date: Sun, 16 Feb 2025 17:18:42 +0100 Subject: [PATCH 5/6] Rearrange contents in completions reference a bit --- docs/reference/completions.md | 48 ++++++++++++++++++++++++----------- 1 file changed, 33 insertions(+), 15 deletions(-) diff --git a/docs/reference/completions.md b/docs/reference/completions.md index fe65d260..07f0b5e7 100644 --- a/docs/reference/completions.md +++ b/docs/reference/completions.md @@ -52,7 +52,7 @@ Here's an example (with HTML completions): See [Scopes][] for more information. -[Scopes]: /guide/extensibility/syntaxdefs.md#scopes +[Scopes]: /guide/extensibility/syntaxdefs.md#scopes **completions** : Array of *completions*. @@ -79,13 +79,23 @@ is identical to the `contents`: ```json { "trigger": "foo", "contents": "foobar" }, +{ "trigger": "foo\ttest", "contents": "foobar" }, ``` -**trigger** +**trigger** {#trigger} : Text that will be displayed in the completions list and will cause the `contents` to be inserted when chosen. + You can use a `\t` tab character + to add an *annotation* for the preceding trigger. + The annotation will be displayed right-aligned, + slightly grayed + and does not affect the trigger itself. + + See also the [`annotation`](#annotation) field + for a more explicit way of defining this. + **contents** : Text to be inserted in the buffer. Supports the same string interpolation features @@ -109,28 +119,36 @@ because we are within a JSON string). { "trigger": "func", "contents": "funcbar", - "annotation": "string", + "annotation": "function", "kind": "function", - "details": "A short description of what this string function does." + "details": "A short description of what this string function does.", } - -{ "trigger": "func\tstring", "contents": "funcbar" } ``` -::: info Added in build 4050. - These do not affect the triggers themselves, - but allow for customization of the appearance of completions in the completions list. -::: +These do not affect the triggers themselves, +but allow for customization of the appearance of completions +in the completions list. + +**annotation** {#annotation} +: Displays as right-aligned gray text to the right of the entry in the completions list. + Does not affect the trigger itself. + + Annotations can also be defined + using a tab character `\t` in [`trigger`](#trigger). + + ::: tip Added in build 4050 {added} + ::: **kind** -: Allows for categorization of the completion via a colored +: Allows for categorization of the completion via a colored kind letter to the left of the entry in the completions list. Colors are determined by the user's color scheme. -**annotation** -: Displays as right-aligned gray text to the right of the entry in the completions list. - Does not affect the trigger itself. - Annotations can also be defined using a tab character `\t` in `trigger`. + ::: tip Added in build 4050 {added} + ::: **details** : Displays at the bottom of the completions list when the entry is highlighted. + + ::: tip Added in build 4050 {added} + ::: From 905c74236d8af1db871bd918263baa46457e8e78 Mon Sep 17 00:00:00 2001 From: FichteFoll Date: Sun, 16 Feb 2025 20:57:52 +0100 Subject: [PATCH 6/6] Address review feedback --- docs/reference/completions.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/docs/reference/completions.md b/docs/reference/completions.md index 07f0b5e7..9e3ac752 100644 --- a/docs/reference/completions.md +++ b/docs/reference/completions.md @@ -90,7 +90,7 @@ is identical to the `contents`: You can use a `\t` tab character to add an *annotation* for the preceding trigger. The annotation will be displayed right-aligned, - slightly grayed + slightly dimmed and does not affect the trigger itself. See also the [`annotation`](#annotation) field @@ -130,10 +130,13 @@ but allow for customization of the appearance of completions in the completions list. **annotation** {#annotation} -: Displays as right-aligned gray text to the right of the entry in the completions list. +: Displays as right-aligned dimmed text + to the right of the entry + in the completions list. Does not affect the trigger itself. - Annotations can also be defined + Before this field was added, + annotations could (and still can) also be defined using a tab character `\t` in [`trigger`](#trigger). ::: tip Added in build 4050 {added}