Merge pull request #123 from sublimetext-io/feature/st4-completions-fields

Add ST4 completions fields to reference

Author: FichteFoll

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
@@ -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
@@ -204,6 +220,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)

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';
@@ -191,6 +192,7 @@ export default defineConfig({
     },
     lineNumbers: true,
     config: md => {
+      md.use(markdownItAttrs);
       md.use(markdownItDeflist);
       md.use(markdownItFootnote);
     },

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-custom-block-tip-code-bg: var(--vp-code-bg);
 
@@ -37,17 +38,19 @@
   --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%);
 }
 
 
 .VPNavBar:not(.has-sidebar):not(.top) {
   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;
@@ -77,3 +80,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);
+}

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,20 +79,23 @@ is identical to the `contents`:
 
 ```json
 { "trigger": "foo", "contents": "foobar" },
-{ "trigger": "foo\ttest", "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
+  slightly dimmed
   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
@@ -108,3 +111,47 @@ 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": "function",
+  "kind": "function",
+  "details": "A short description of what this string function does.",
+}
+```
+
+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 dimmed text
+  to the right of the entry
+  in the completions list.
+  Does not affect the trigger itself.
+
+  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}
+  :::
+
+**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.
+
+  ::: 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}
+  :::

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",