From dbae1ed236dd89a8e8a19e47d06cf205bda5b3a9 Mon Sep 17 00:00:00 2001 From: artisticat <100622574+artisticat1@users.noreply.github.com> Date: Mon, 26 Aug 2024 15:51:03 +0100 Subject: [PATCH] docs: update readme and docs --- DOCS.md | 8 +++-- README.md | 94 ++++++++++++++++++++++++++++++++++--------------------- 2 files changed, 65 insertions(+), 37 deletions(-) diff --git a/DOCS.md b/DOCS.md index 5e3a3b6..f633a86 100644 --- a/DOCS.md +++ b/DOCS.md @@ -1,6 +1,6 @@ # Documentation ## Snippets -Snippets are formatted as follows: +*Snippets* are shortcuts that allow you to insert certain text based on certain triggers. The structure of a snippet is as follows: ```typescript { @@ -58,7 +58,11 @@ No mode specified means that this snippet can be triggered _at all times_. Multi ### Regex snippets -To create a regex snippet, you can +[Regular expressions](https://en.wikipedia.org/wiki/Regular_expression) are sequences of characters that specify a match pattern. (If you're unfamiliar with regex, [here's a tutorial you might like to check out](https://regexone.com).) + +In Latex Suite, you can use regular expressions to write more general snippets that expand according to some match pattern that you specify. + + To create a regex snippet, you can - use the `r` option, or - make the `trigger` a RegExp literal (such as `/regex-goes-here/`). diff --git a/README.md b/README.md index 6cbe7dd..0f1d303 100644 --- a/README.md +++ b/README.md @@ -30,17 +30,20 @@ To get started, type "dm" to enter display math mode. Try typing the following: **Have a look at the [cheatsheet](#cheatsheet)** for a list of commonly used default snippets. -Once these feel familiar, you can check out the [default snippets](https://github.com/artisticat1/obsidian-latex-suite/blob/main/src/default_snippets.js) for more commands. e.g. +Once these feel familiar, you can check out the [**default snippets**](https://github.com/artisticat1/obsidian-latex-suite/blob/main/src/default_snippets.js) for more commands. e.g. - "par Tab f Tab x Tab" → "\\frac{\\partial f}{\\partial x}". - "dint Tab 2pi Tab sin @t Tab @t Tab" → "\\int_{0}^{2\pi} \\sin \\theta \\, d\\theta". -You can also add your own snippets! [See here for more info on writing snippets](#snippets). You can [view snippets written by others and share your own snippets here](https://github.com/artisticat1/obsidian-latex-suite/discussions/50). +You can also add your own snippets! [For more info on writing snippets, see **here**](#snippets). You can [view snippets written by others and share your own snippets here](https://github.com/artisticat1/obsidian-latex-suite/discussions/50). + +Aside from snippets, the plugin also comes with several other features that aim to make writing LaTeX easier. ## Features + ### Auto-fraction Lets you type "1/x" instead of "\frac{1}{x}". @@ -59,46 +62,42 @@ Once done typing the denominator, press Tab to exit the fraction. ### Matrix shortcuts While inside a matrix, array, align, or cases environment, -- Pressing Tab will insert the "&" symbol -- Pressing Enter will insert "\\\\" and move to a new line -- Pressing Shift + Enter will move to the end of the next line (can be used to exit the matrix) +- Pressing Tab will insert the "&" symbol. +- Pressing Enter will insert "\\\\" and move to a new line. +- Pressing Shift + Enter will move to the end of the next line (which you can use to exit the matrix). ![matrix shortcuts](https://raw.githubusercontent.com/artisticat1/obsidian-latex-suite/main/gifs/matrix_shortcuts.gif) ### Conceal -*This feature must be enabled in settings!* +*This feature must be enabled in the plugin settings.* -Make your equations more readable by hiding LaTeX code, instead rendering it in a pretty format. +Make your equations more readable by hiding LaTeX markup and instead displaying it in a pretty format. For example, "\dot{x}^{2} + \dot{y}^{2}" will be displayed as "ẋ² + ẏ²". -To reveal the LaTeX code, move the cursor over it. +"\sqrt{ 1-\beta^{2} }" will be displayed as "√{ 1-β² }". + +To reveal the LaTeX syntax, move your cursor over it. -![conceal demo](https://raw.githubusercontent.com/artisticat1/obsidian-latex-suite/main/gifs/conceal.png) ![conceal demo 2](https://raw.githubusercontent.com/artisticat1/obsidian-latex-suite/main/gifs/conceal.gif) +![conceal demo](https://raw.githubusercontent.com/artisticat1/obsidian-latex-suite/main/gifs/conceal.png) ### Tabout -- Pressing Tab while the cursor is at the end of an equation will move the cursor outside the $ symbols. -- Otherwise, pressing Tab will advance the cursor to the next closing bracket: ), ], }, >, or |. +To make it easier to navigate and exit equations, + +- Pressing Tab while the cursor is at the end of an equation will move the cursor outside the `$` symbols. +- Otherwise, pressing Tab will advance the cursor to the next closing bracket: `)`, `]`, `}`, `>`, or `|`. ### Preview inline math -When the cursor is inside inline math, a popup window showing the rendered math will be displayed. +When your cursor is inside inline math, a popup window showing the rendered math will be displayed. -### Color & highlight matching brackets -- Matching brackets are rendered in the same color, to help with readability. -- When the cursor is adjacent to a bracket, that bracket and its pair will be highlighted. -- When the cursor is inside brackets, the enclosing brackets will be highlighted. - -![color and highlight matching brackets demo](https://raw.githubusercontent.com/artisticat1/obsidian-latex-suite/main/gifs/color_brackets.gif) - - ### Visual snippets Sometimes you want to annotate math, or cancel or cross out terms. Selecting some math with the cursor and typing @@ -112,18 +111,41 @@ Sometimes you want to annotate math, or cancel or cross out terms. Selecting som ### Auto-enlarge brackets -When a snippet containing "\\sum", "\\int" or "\\frac" is triggered, any enclosing brackets will be enlarged with "\\left" and "\\right". +When a snippet containing "\\sum", "\\int" or "\\frac" is triggered, any enclosing brackets will automatically be enlarged with "\\left" and "\\right". ![auto-enlarge brackets](https://raw.githubusercontent.com/artisticat1/obsidian-latex-suite/main/gifs/auto-enlarge_brackets.gif) +### Color and highlight matching brackets + +To help make your equations more readable, + +- Matching brackets will be displayed in the same color. +- When your cursor is adjacent to a bracket, that bracket and its pair will be highlighted. +- When your cursor is inside brackets, the enclosing brackets will be highlighted. + +![color and highlight matching brackets demo](https://raw.githubusercontent.com/artisticat1/obsidian-latex-suite/main/gifs/color_brackets.gif) + + ### Editor commands -- Box current equation – surround the equation the cursor is currently in with a box. -- Select current equation – select the equation the cursor is currently in. + +The plugin also adds the following commands to the Command palette: + +- **Box current equation** — surround the equation the cursor is currently in with a box, using "\boxed{ ... }". +- **Select current equation** – select the equation the cursor is currently in. ### Snippets -Snippets are formatted as follows: + +*Snippets* are shortcuts that allow you to insert certain text based on certain triggers. For example, the default snippet + +```typescript +{trigger: "@l", replacement: "\\lambda", options: "mA"} +``` + +will expand "@l" to "\lambda". + +Snippets can be edited in the plugin settings. The structure of a snippet is as follows: ```typescript { @@ -159,7 +181,9 @@ Snippets are formatted as follows: Insert **tabstops** for the cursor to jump to by writing "$0", "$1", etc. in the `replacement`. -For more details on writing snippets, including **regex** snippets and **function** snippets, [see the **documentation** here](DOCS.md). You can [view snippets written by others and share your own snippets here](https://github.com/artisticat1/obsidian-latex-suite/discussions/50). +For examples and more details on writing snippets, including **regex** snippets and **function** snippets, [have a look at the **documentation**](DOCS.md). + +You can [view snippets written by others and share your own snippets here](https://github.com/artisticat1/obsidian-latex-suite/discussions/50). > [!WARNING] > Snippet files are interpreted as JavaScript and can execute arbitrary code. @@ -219,21 +243,21 @@ When running a snippet that **moves the cursor inside brackets {}, press Ta | @o | \\omega | | | | ome | \\omega | | | -For greek letters with short names (2-3 characters), just type their name, -e.g. "pi" → "\\pi" +For Greek letters with short names (2-3 characters), just type their name, +e.g. "pi" → "\\pi". -## Contributing -Any contributions and PRs are welcome! +## Acknowledgements +- [@tth05](https://github.com/tth05)'s [Obsidian Completr](https://github.com/tth05/obsidian-completr) for the basis of the tabstop code. +- [Dynamic Highlights](https://github.com/nothingislost/obsidian-dynamic-highlights/blob/master/src/settings/ui.ts) for reference. +- [Quick Latex for Obsidian](https://github.com/joeyuping/quick_latex_obsidian) for inspiration. -## Acknowledgements -- [@tth05](https://github.com/tth05)'s [Obsidian Completr](https://github.com/tth05/obsidian-completr) for the basis of the tabstop code -- [Dynamic Highlights](https://github.com/nothingislost/obsidian-dynamic-highlights/blob/master/src/settings/ui.ts) for reference -- [Quick Latex for Obsidian](https://github.com/joeyuping/quick_latex_obsidian) for inspiration +## Contributing +Any contributions and PRs are welcome! ## Support -If you like this plugin and want to say thanks, you can buy me a coffee here! +If you like this plugin and want to say thanks, you can buy me a coffee here. -Buy Me a Coffee at ko-fi.com +Buy Me a Coffee at ko-fi.com