feat: convert introduction.typ to README.md (#479)

* dev: supports some functions for README

* feat: convert introduction.typ to README.md

README.md

@@ -1,12 +1,14 @@
+<!-- This file is generated by scripts/link-docs.mjs from docs/tinymist/introduction.typ. Do not edit manually. -->
 # Tinymist
 
 Tinymist [ˈtaɪni mɪst] is an integrated language service for [Typst](https://typst.app/) [taɪpst]. You can also call it "微霭" [wēi ǎi] in Chinese.
 
 It contains:
-- an analyzing library for Typst, see [tinymist-query](./crates/tinymist-query/).
-- a CLI for Typst, see [tinymist](./crates/tinymist/).
-  - which provides a language server for Typst.
-- a VSCode extension for Typst, see [Tinymist VSCode Extension](./editors/vscode/).
+- an analyzing library for Typst, see [tinymist-query](https://github.com/Myriad-Dreamin/tinymist/tree/main/crates/tinymist-query).
+- a CLI for Typst, see [tinymist](https://github.com/Myriad-Dreamin/tinymist/tree/main/crates/tinymist/).
+  - which provides a language server for Typst, see [Langauge Features](https://myriad-dreamin.github.io/tinymist//feature/language.html).
+  - which provides a preview server for Typst, see [Preview Feature](https://myriad-dreamin.github.io/tinymist//feature/preview.html).
+- a VSCode extension for Typst, see [Tinymist VSCode Extension](https://github.com/Myriad-Dreamin/tinymist/tree/main/editors/vscode/).
 
 ## Features
 
@@ -22,7 +24,7 @@ Language service (LSP) features:
   - (Todo) Highlight all captures in a closure context.
   - (Todo) Highlight all occurrences of a symbol in a document.
 - [Document symbols](https://code.visualstudio.com/docs/getstarted/userinterface#_outline-view)
-  - Also known as "document outline" or "table of contents" **in Typst**.
+  - Also known as "document outline" or "table of contents" _in Typst_.
 - [Folding ranges](https://burkeholland.gitbook.io/vs-code-can-do-that/exercise-3-navigation-and-refactoring/folding-sections)
   - You can collapse code/content blocks and headings.
 - [Goto definitions](https://code.visualstudio.com/api/language-extensions/programmatic-language-features#show-definitions-of-a-symbol)
@@ -60,14 +62,13 @@ Extra features:
   - Click a button in template gallery to initialize a new project with a template. (`tinymist.initTemplate` and `tinymist.initTemplateInPlace`)
   - Trace execution in current document. (`tinymist.profileCurrentFile`)
 
-
 ## Installation
 
 Follow the instructions to enable tinymist in your favorite editor.
-+ [Helix](./editors/helix/README.md)
-+ [Neovim](./editors/neovim/README.md)
-+ [VSCode](./editors/vscode/README.md)
-+ [Zed](editors/zed/README.md)
+1. [Helix](https://github.com/Myriad-Dreamin/tinymist/tree/main/editors/helix/README.md)
+1. [Neovim](https://github.com/Myriad-Dreamin/tinymist/tree/main/editors/neovim/README.md)
+1. [VSCode](https://github.com/Myriad-Dreamin/tinymist/tree/main/editors/vscode/README.md)
+1. [Zed](https://github.com/Myriad-Dreamin/tinymist/tree/main/editors/zed/README.md)
 
 ## Documentation
 
@@ -75,8 +76,10 @@ See [Online Documentation](https://myriad-dreamin.github.io/tinymist/).
 
 ## Packaging
 
+
 [![Packaging status](https://repology.org/badge/vertical-allrepos/tinymist.svg)](https://repology.org/project/tinymist/versions)
 
+
 ## Roadmap
 
 After development for two months, most of the features are implemented. There are still some features to be implemented, but I would like to leave them in typst v0.12.0. I'll also pick some of them to implement on my weekends. Also please feel free to contribute if you are interested in the following features.
@@ -84,7 +87,7 @@ After development for two months, most of the features are implemented. There ar
 - Documentation and refactoring: It is my current focus.
 - Spell checking: There is already a branch but no suitable (default) spell checking library is found.
 - Periscope renderer: It is disabled since vscode reject to render SVGs containing foreignObjects.
-- Inlay hint: It is disabled **by default** because of performance issues.
+- Inlay hint: It is disabled _by default_ because of performance issues.
 - Find references of labels, dictionary fields, and named function arguments.
 - Go to definition of dictionary fields and named function arguments.
 - Autocompletion for raw language tags.
@@ -97,5 +100,5 @@ Please read the [CONTRIBUTING.md](CONTRIBUTING.md) file for contribution guideli
 ## Acknowledgements
 
 - Partially code is inherited from [typst-lsp](https://github.com/nvarner/typst-lsp)
-- The [integrating](https://github.com/Myriad-Dreamin/tinymist/tree/main/editors/vscode#symbol-view) *offline* handwritten-stroke recognizer is powered by [Detypify](https://detypify.quarticcat.com/).
+- The [integrating](https://github.com/Myriad-Dreamin/tinymist/tree/main/editors/vscode#symbol-view) **offline** handwritten-stroke recognizer is powered by [Detypify](https://detypify.quarticcat.com/).
 - The [integrating](https://github.com/Myriad-Dreamin/tinymist/tree/main/editors/vscode#preview) preview service is powered by [typst-preview](https://github.com/Enter-tainer/typst-preview).

crates/typlite/src/library.rs

@@ -5,6 +5,10 @@ use value::*;
 pub fn library() -> Scopes<Value> {
     let mut scopes = Scopes::new();
     scopes.define("link", link as RawFunc);
+    scopes.define("kbd", kbd as RawFunc);
+    // todo: how to import this function correctly?
+    scopes.define("cross-link", cross_link as RawFunc);
+    scopes.define("md-alter", md_alter as RawFunc);
     scopes.define("image", image as RawFunc);
     scopes.define("figure", figure as RawFunc);
     scopes
@@ -42,3 +46,31 @@ pub fn figure(mut args: Args) -> Result<Value> {
         _ => Err("figure only accepts image as body".into()),
     }
 }
+
+/// Evaluate a `kbd` element.
+pub fn kbd(mut args: Args) -> Result<Value> {
+    let key = get_pos_named!(args, key: EcoString);
+
+    Ok(Value::Content(eco_format!("<kbd>{key}</kbd>")))
+}
+
+/// Evaluate a `cross-link`.
+pub fn cross_link(mut args: Args) -> Result<Value> {
+    let dest = get_pos_named!(args, dest: EcoString);
+    let body = get_pos_named!(args, body: Content);
+
+    let dest = std::path::Path::new(dest.as_str()).with_extension("html");
+
+    Ok(Value::Content(eco_format!(
+        "[{body}](https://myriad-dreamin.github.io/tinymist/{dest})",
+        dest = dest.to_string_lossy()
+    )))
+}
+
+/// Evaluate a markdown alteration.
+pub fn md_alter(mut args: Args) -> Result<Value> {
+    let _left = get_pos_named!(args, left: Content);
+    let right = get_pos_named!(args, right: LazyContent);
+
+    Ok(Value::Content(right.0))
+}

crates/typlite/src/value.rs

@@ -27,6 +27,14 @@ impl fmt::Display for Content {
     }
 }
 
+pub struct LazyContent(pub EcoString);
+
+impl fmt::Display for LazyContent {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        write!(f, "{}", self.0)
+    }
+}
+
 pub struct Args<'a> {
     pub vm: &'a mut TypliteWorker,
     pub args: ast::Args<'a>,
@@ -154,3 +162,14 @@ impl<'a> Eval<'a> for Content {
         Ok(Self(vm.convert(node)?))
     }
 }
+
+impl<'a> Eval<'a> for LazyContent {
+    fn eval(node: &'a SyntaxNode, vm: &mut TypliteWorker) -> Result<Self> {
+        let node = match node.cast() {
+            Some(s @ ast::Closure { .. }) => s.body().to_untyped(),
+            None => node,
+        };
+
+        Ok(Self(vm.convert(node)?))
+    }
+}

docs/tinymist/introduction.typ

@@ -8,11 +8,104 @@ Tinymist [ˈtaɪni mɪst] is an integrated language service for #link("https://t
 It contains:
 - an analyzing library for Typst, see #link("https://github.com/Myriad-Dreamin/tinymist/tree/main/crates/tinymist-query")[tinymist-query].
 - a CLI for Typst, see #link("https://github.com/Myriad-Dreamin/tinymist/tree/main/crates/tinymist/")[tinymist].
-  - which provides a language server for Typst, see #cross-link("/language-features.typ")[Langauge Features].
-  - which provides a preview server for Typst, see #cross-link("/preview-feature.typ")[Preview Feature].
+  - which provides a language server for Typst, see #cross-link("/feature/language.typ")[Langauge Features].
+  - which provides a preview server for Typst, see #cross-link("/feature/preview.typ")[Preview Feature].
 - a VSCode extension for Typst, see #link("https://github.com/Myriad-Dreamin/tinymist/tree/main/editors/vscode/")[Tinymist VSCode Extension].
 
-Further Reading:
+== Features
 
-- #cross-link("/overview.typ")[Overview of Service]
-- #cross-link("/rs/tinymist/index.typ")[Tinymist Crate Docs (for Developers)]
+Language service (LSP) features:
+
+- #link("https://code.visualstudio.com/api/language-extensions/semantic-highlight-guide")[Semantic highlighting]
+  - Also known as "syntax highlighting".
+- #link("https://code.visualstudio.com/api/language-extensions/programmatic-language-features#provide-diagnostics")[Diagnostics]
+  - Also known as "error checking" or "error reporting".
+- #link("https://code.visualstudio.com/api/language-extensions/programmatic-language-features#highlight-all-occurrences-of-a-symbol-in-a-document")[Document highlight]
+  - Highlight all break points in a loop context.
+  - (Todo) Highlight all exit points in a function context.
+  - (Todo) Highlight all captures in a closure context.
+  - (Todo) Highlight all occurrences of a symbol in a document.
+- #link("https://code.visualstudio.com/docs/getstarted/userinterface#_outline-view")[Document symbols]
+  - Also known as "document outline" or "table of contents" _in Typst_.
+- #link("https://burkeholland.gitbook.io/vs-code-can-do-that/exercise-3-navigation-and-refactoring/folding-sections")[Folding ranges]
+  - You can collapse code/content blocks and headings.
+- #link("https://code.visualstudio.com/api/language-extensions/programmatic-language-features#show-definitions-of-a-symbol")[Goto definitions]
+  - Right-click on a symbol and select "Go to Definition".
+  - Or ctrl+click on a symbol.
+- #link("https://code.visualstudio.com/api/language-extensions/programmatic-language-features#find-all-references-to-a-symbol")[References]
+  - Right-click on a symbol and select "Go to References" or "Find References".
+  - Or ctrl+click on a symbol.
+- #link("https://code.visualstudio.com/api/language-extensions/programmatic-language-features#show-hovers")[Hover tips]
+  - Also known as "hovering tooltip".
+- #link("https://www.jetbrains.com/help/idea/inlay-hints.html")[Inlay hints]
+  - Inlay hints are special markers that appear in the editor and provide you with additional information about your code, like the names of the parameters that a called method expects.
+- #link("https://code.visualstudio.com/api/language-extensions/programmatic-language-features#show-color-decorators")[Color Provider]
+  - View all inlay colorful label for color literals in your document.
+  - Change the color literal's value by a color picker or its code presentation.
+- #link("https://code.visualstudio.com/blogs/2017/02/12/code-lens-roundup")[Code Lens]
+  - Should give contextual buttons along with code. For example, a button for exporting your document to various formats at the start of the document.
+- #link("https://code.visualstudio.com/api/language-extensions/programmatic-language-features#rename-symbols")[Rename symbols]
+- #link("https://code.visualstudio.com/api/language-extensions/programmatic-language-features#help-with-function-and-method-signatures")[Help with function and method signatures]
+- #link("https://code.visualstudio.com/api/language-extensions/programmatic-language-features#show-all-symbol-definitions-in-folder")[Workspace Symbols]
+- #link("https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-code-actions")[Code Action]
+  - Increasing/Decreasing heading levels.
+- #link("https://github.com/rust-lang/rust-analyzer/blob/master/docs/dev/lsp-extensions.md#on-enter")[experimental/onEnter]
+  - #kbd("Enter") inside triple-slash comments automatically inserts `///`
+  - #kbd("Enter") in the middle or after a trailing space in `//` inserts `//`
+  - #kbd("Enter") inside `//!` doc comments automatically inserts `//!`
+
+Extra features:
+
+- Compiles to PDF on save (configurable to as-you-type, or other options)
+- Provides code lenses for exporting to various formats (PDF, SVG, PNG, etc.)
+- Provides a status bar item to show the current document's compilation status and words count.
+- #link("https://github.com/Myriad-Dreamin/tinymist/tree/main/tools/editor-tools")[Editor tools]:
+  - View a list of templates in template gallery. (`tinymist.showTemplateGallery`)
+  - Click a button in template gallery to initialize a new project with a template. (`tinymist.initTemplate` and `tinymist.initTemplateInPlace`)
+  - Trace execution in current document. (`tinymist.profileCurrentFile`)
+
+== Installation
+
+Follow the instructions to enable tinymist in your favorite editor.
++ #link("https://github.com/Myriad-Dreamin/tinymist/tree/main/editors/helix/README.md")[Helix]
++ #link("https://github.com/Myriad-Dreamin/tinymist/tree/main/editors/neovim/README.md")[Neovim]
++ #link("https://github.com/Myriad-Dreamin/tinymist/tree/main/editors/vscode/README.md")[VSCode]
++ #link("https://github.com/Myriad-Dreamin/tinymist/tree/main/editors/zed/README.md")[Zed]
+
+== Documentation
+
+See #link("https://myriad-dreamin.github.io/tinymist/")[Online Documentation].
+
+== Packaging
+
+#link(
+  "https://repology.org/project/tinymist/versions",
+  md-alter(
+    "Packaging status",
+    () => image("https://repology.org/badge/vertical-allrepos/tinymist.svg", alt: "Packaging status"),
+  ),
+)
+
+
+== Roadmap
+
+After development for two months, most of the features are implemented. There are still some features to be implemented, but I would like to leave them in typst v0.12.0. I'll also pick some of them to implement on my weekends. Also please feel free to contribute if you are interested in the following features.
+
+- Documentation and refactoring: It is my current focus.
+- Spell checking: There is already a branch but no suitable (default) spell checking library is found.
+- Periscope renderer: It is disabled since vscode reject to render SVGs containing foreignObjects.
+- Inlay hint: It is disabled _by default_ because of performance issues.
+- Find references of labels, dictionary fields, and named function arguments.
+- Go to definition of dictionary fields and named function arguments.
+- Autocompletion for raw language tags.
+- Improve symbol view's appearance.
+
+== Contributing
+
+Please read the #link("CONTRIBUTING.md")[CONTRIBUTING.md] file for contribution guidelines.
+
+== Acknowledgements
+
+- Partially code is inherited from #link("https://github.com/nvarner/typst-lsp")[typst-lsp]
+- The #link("https://github.com/Myriad-Dreamin/tinymist/tree/main/editors/vscode#symbol-view")[integrating] *offline* handwritten-stroke recognizer is powered by #link("https://detypify.quarticcat.com/")[Detypify].
+- The #link("https://github.com/Myriad-Dreamin/tinymist/tree/main/editors/vscode#preview")[integrating] preview service is powered by #link("https://github.com/Enter-tainer/typst-preview")[typst-preview].

docs/tinymist/mod.typ

@@ -17,9 +17,8 @@
   #raw(it + "()", lang: "typc") <typst-raw-func>
 ]
 
-#show <typst-raw-func>: it => {
-  it.lines.at(0).body.children.slice(0, -2).join()
-}
+#let kbd = raw
+#let md-alter(left, right) = left
 
 #let colors = (blue.lighten(10%), olive, eastern)
 #import fletcher.shapes: diamond

package.json

@@ -16,7 +16,9 @@
     "build:preview": "cd tools/typst-preview-frontend && yarn run build && rimraf ../../crates/tinymist-assets/src/typst-preview.html && cpr ./dist/index.html ../../crates/tinymist-assets/src/typst-preview.html",
     "docs": "shiroa serve -w . docs/tinymist",
     "docs:rs": "cargo doc --workspace --no-deps",
-    "test:grammar": "cd syntaxes/textmate && yarn run test"
+    "test:grammar": "cd syntaxes/textmate && yarn run test",
+    "build:typlite": "cd contrib/typlite && cargo build",
+    "typlite": "cd contrib/typlite && target/debug/typlite"
   },
   "dependencies": {},
   "devDependencies": {

scripts/link-docs.mjs

@@ -0,0 +1,48 @@
+
+import {resolve} from 'path';
+import {fileURLToPath} from 'url';
+import * as fs from 'fs';
+import {execSync} from 'child_process';
+
+const filename = fileURLToPath(import.meta.url);
+const root = resolve(filename, '../..');
+const dry = process.argv.includes('--dry');
+
+const yarn = (cmd, stdio = 'inherit') => {
+    const script = `yarn run ${cmd}`;
+    if (dry) {
+        return script;
+    }
+    return execSync(script, {stdio});
+};
+const typlite = (input, output = "-") => {
+    if (output === "-") {
+        // return stdout
+        const res = yarn(`--silent typlite ${input} -`, 'pipe');
+        return res.toString();
+    }
+
+    return yarn(`typlite ${input} ${output}`);
+};
+
+const convert = async (inp, out, opts) => {
+    const input = resolve(root, inp);
+    const output = resolve(root, out);
+    const { before } = opts || {};
+
+    const res = typlite(input).trim();
+    if (dry) {
+        console.log(res);
+        return;
+    }
+
+    await fs.promises.writeFile(output, `<!-- This file is generated by scripts/link-docs.mjs from ${inp}. Do not edit manually. -->\n${before || ''}${res}\n`);
+};
+
+const main = async () => {
+    await Promise.all([
+        convert('docs/tinymist/introduction.typ', 'README.md', { before: "# Tinymist\n\n" }),
+    ])
+};
+
+main().catch(console.error);

typ/templates/page.typ

@@ -142,6 +142,10 @@
     }
   }
 
+  show <typst-raw-func>: it => {
+    it.lines.at(0).body.children.slice(0, -2).join()
+  }
+
   // Main body.
   set par(justify: true)