From 97c5c741137ecc363630c58797901f1eb829c1bb Mon Sep 17 00:00:00 2001 From: marv Date: Fri, 2 Feb 2024 20:44:14 -0800 Subject: Add Prettier Formatting for Markdown Files and Pre-Commit Hook (#543) * Install prettier, add prettierignore * Add precommit hook for md * Prettier format md files --- docs/templates.md | 506 +++++++++++++++++++++++++++++++----------------------- 1 file changed, 294 insertions(+), 212 deletions(-) (limited to 'docs/templates.md') diff --git a/docs/templates.md b/docs/templates.md index ddab4390..3f51dc98 100644 --- a/docs/templates.md +++ b/docs/templates.md @@ -5,7 +5,6 @@ Yomitan supports several custom Handlebars helpers for rendering templates. The source code for these templates can be found [here](../ext/js/templates/sandbox/anki-template-renderer.js). - ### `dumpObject` Converts an object to a pretty-printed JSON string. @@ -14,33 +13,38 @@ This function can be helpful for debugging values when creating templates.
Syntax: - {{dumpObject object}} +{{dumpObject object}} - * _`object`_
- The object to convert. +- _`object`_
+The object to convert.
Example: + ```handlebars 
{{dumpObject .}}
``` - Output: +Output: + + ```html 
{
       "key": "value"
   }
``` - Preview: +Preview: + + ```html { "key": "value" } ``` -
+ ### `furigana` @@ -49,34 +53,37 @@ Converts a definition or expression/reading pair to its furigana representation.
Syntax: - {{furigana definition}}
- {{furigana expression reading}}
+{{furigana definition}}
+{{furigana expression reading}}
- * _`definition`_
- The definition to convert. - * _`expression`_
- The expression to convert. - * _`reading`_
- The reading to convert. +- _`definition`_
+ The definition to convert. +- _`expression`_
+ The expression to convert. +- _`reading`_
+The reading to convert.
Example: + ```handlebars {{furigana .}} {{furigana "読む" "よむ"}} ``` - Output: +Output: + + ```html 読よむ ``` - Preview +Preview + 
読よむ
- ### `furiganaPlain` Converts a definition or expression/reading pair to its simplified furigana representation. @@ -84,30 +91,33 @@ Converts a definition or expression/reading pair to its simplified furigana repr
Syntax: - {{furiganaPlain definition}} - {{furiganaPlain expression reading}}
+{{furiganaPlain definition}} +{{furiganaPlain expression reading}}
- * _`definition`_
- The definition to convert. - * _`expression`_
- The expression to convert. - * _`reading`_
- The reading to convert. +- _`definition`_
+ The definition to convert. +- _`expression`_
+ The expression to convert. +- _`reading`_
+The reading to convert.
Example: + ```handlebars {{~furiganaPlain .~}} {{furiganaPlain "読む" "よむ"}} ``` - Output: +Output: + + ```html 読[よ]む ``` -
+ ### `multiLine` @@ -116,11 +126,13 @@ Replaces newline characters with a forced HTML line break `
`.
Syntax: - {{#multiLine}}text with multiple lines{{/multiLine}} +{{#multiLine}}text with multiple lines{{/multiLine}} +
Example: + ```handlebars {{#multiLine~}} some @@ -129,16 +141,18 @@ Replaces newline characters with a forced HTML line break `
`. {{~/multiLine}} ``` - Output: +Output: + + ```html some
multiline
text ``` - Preview: +Preview: + 
some
multiline
text
- ### `regexReplace` Uses a [regular expression](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions) to replace a pattern with the specified text. @@ -146,32 +160,35 @@ Uses a [regular expression](https://developer.mozilla.org/en-US/docs/Web/JavaScr
Syntax: - {{#regexReplace regex replacement [flags]}}text-to-modify{{/regexReplace}}
- {{regexReplace regex replacement [flags] [text-to-modify]...}}
+{{#regexReplace regex replacement [flags]}}text-to-modify{{/regexReplace}}
+{{regexReplace regex replacement [flags] [text-to-modify]...}}
- * _`regex`_
- The raw string used to create the regular expression. This value is passed to the [`RegExp`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/RegExp) constructor. - * _`replacement`_
- The text used to replace pattern matches. This supports the standard [special capture group replacements](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace#Specifying_a_string_as_a_parameter) as supported by the web browser. - * _`flags`_ _(optional)_
- Optional flags to pass to the [`RegExp`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/RegExp) constructor. - * _`text-to-modify`_
- The text that the regular expression is applied to. - If multiple arguments are present, they are all concatenated. +- _`regex`_
+ The raw string used to create the regular expression. This value is passed to the [`RegExp`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/RegExp) constructor. +- _`replacement`_
+ The text used to replace pattern matches. This supports the standard [special capture group replacements](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace#Specifying_a_string_as_a_parameter) as supported by the web browser. +- _`flags`_ _(optional)_
+ Optional flags to pass to the [`RegExp`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/RegExp) constructor. +- _`text-to-modify`_
+The text that the regular expression is applied to. +If multiple arguments are present, they are all concatenated.
Example: + ```handlebars {{#regexReplace "\(([^)]*)\)" "$1" "g"~}}Here is (some) (text) (in) (parentheses){{~/regexReplace}} ``` - Output: +Output: + + ```html Here is some text in parentheses ``` -
+ ### `regexMatch` @@ -180,30 +197,33 @@ Uses a [regular expression](https://developer.mozilla.org/en-US/docs/Web/JavaScr
Syntax: - {{#regexMatch regex [flags]}}text-to-modify{{/regexMatch}}
- {{regexMatch regex [flags] [text-to-modify]...}}
+{{#regexMatch regex [flags]}}text-to-modify{{/regexMatch}}
+{{regexMatch regex [flags] [text-to-modify]...}}
- * _`regex`_
- The raw string used to create the regular expression. This value is passed to the [`RegExp`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/RegExp) constructor. - * _`flags`_ _(optional)_
- Optional flags to pass to the [`RegExp`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/RegExp) constructor. - * _`text-to-modify`_
- The text that the regular expression is applied to. - If multiple arguments are present, they are all concatenated. +- _`regex`_
+ The raw string used to create the regular expression. This value is passed to the [`RegExp`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/RegExp) constructor. +- _`flags`_ _(optional)_
+ Optional flags to pass to the [`RegExp`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/RegExp) constructor. +- _`text-to-modify`_
+The text that the regular expression is applied to. +If multiple arguments are present, they are all concatenated.
Example: + ```handlebars {{#regexMatch "\(([^)]*)\)" "g"~}}Here is (some) (text) (in) (parentheses){{~/regexMatch}} ``` - Output: +Output: + + ```html (some)(text)(in)(parentheses) ``` -
+ ### `mergeTags` @@ -212,28 +232,31 @@ Creates a set of all unique tags for the definition and returns a text represent
Syntax: - {{mergeTags definition isGroupMode isMergeMode}} +{{mergeTags definition isGroupMode isMergeMode}} - * _`definition`_
- The root definition object. - * _`isGroupMode`_ _(optional)_
- Whether or not the display mode is the 'group' mode. - * _`isMergeMode`_
- Whether or not the display mode is the 'merge' mode. +- _`definition`_
+ The root definition object. +- _`isGroupMode`_ _(optional)_
+ Whether or not the display mode is the 'group' mode. +- _`isMergeMode`_
+Whether or not the display mode is the 'merge' mode.
Example: + ```handlebars {{~mergeTags definition group merge~}} ``` - Output: +Output: + + ```html v5m, vt, JMdict (English) ``` -
+ ### `#eachUpTo` @@ -243,34 +266,37 @@ If the iterable is falsy or empty, the `else` condition will be used.
Syntax: - {{#eachUpTo iterable maxCount}}(modification){{else}}(else-modification){{/eachUpTo}} +{{#eachUpTo iterable maxCount}}(modification){{else}}(else-modification){{/eachUpTo}} - * _`iterable`_
- The object that should be looped over. A JavaScript [`for...of`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for...of) loop is used, so the object only needs to be iterable. - * _`maxCount`_ _(optional)_
- The maximum number of entries to loop over. - * _`modification`_
- The template used to modify the value. The context is changed to the current item of iteration. - * _`else-modification`_
- The template used in case the iterable is falsy or empty. The context is unchanged. +- _`iterable`_
+ The object that should be looped over. A JavaScript [`for...of`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for...of) loop is used, so the object only needs to be iterable. +- _`maxCount`_ _(optional)_
+ The maximum number of entries to loop over. +- _`modification`_
+ The template used to modify the value. The context is changed to the current item of iteration. +- _`else-modification`_
+The template used in case the iterable is falsy or empty. The context is unchanged.
Example: + ```handlebars {{~#eachUpTo someArray 5}}{{{.}}}
{{else}}Empty{{/mergeTags~}} ``` - Output: +Output: + + ```html someArray[0]
someArray[1]
someArray[2]
someArray[3]
someArray[4]
``` - Preview: +Preview: + 
someArray[0]
someArray[1]
someArray[2]
someArray[3]
someArray[4]
- ### `spread` Uses the JavaScript [spread](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Spread_syntax) operator to convert one or more iterables into a single array. @@ -279,71 +305,77 @@ This allows it to be used similar to an [`Array.concat`](https://developer.mozil
Syntax: - {{spread iterable1 iterable2 ... iterableN}} +{{spread iterable1 iterable2 ... iterableN}} - * _`iterableN`_
- A variable amount of iterable objects to combine into a single array. +- _`iterableN`_
+A variable amount of iterable objects to combine into a single array.
Example: + ```handlebars {{#each (spread array1 array2)}}{{{.}}}
{{/each}} ``` - Output: +Output: + + ```html array1[0]
array1[1]
array2[0]
array2[1]
``` - Preview: +Preview: + 
array1[0]
array1[1]
array2[0]
array2[1]
- ### `op` Performs a simple operation on one, two, or three arguments. The operations available are: -* Unary operators: `+`, `-`, `~`, `!` -* Binary operators: `+`, `-`, `/`, `*`, `%`, `**`, `==`, `!=`, `===`, `!==`, `<`, `<=`, `>`, `>=`, `<<`, `>>`, `>>>`, `&`, `|`, `^`, `&&`, `||` -* Ternary operators: `?:` +- Unary operators: `+`, `-`, `~`, `!` +- Binary operators: `+`, `-`, `/`, `*`, `%`, `**`, `==`, `!=`, `===`, `!==`, `<`, `<=`, `>`, `>=`, `<<`, `>>`, `>>>`, `&`, `|`, `^`, `&&`, `||` +- Ternary operators: `?:` If an unknown operator is specified, the `undefined` value is returned.
Syntax: - {{op operator operand1 [operand2] [operand3]}} +{{op operator operand1 [operand2] [operand3]}} - * _`operator`_
- One of the unary, binary, or ternary operators. - * _`operand1`_
- The first operand of the operation. - * _`operand2`_ _(Optional)_
- The second operand of the operation. - * _`operand3`_ _(Optional)_
- The third operand of the operation. +- _`operator`_
+ One of the unary, binary, or ternary operators. +- _`operand1`_
+ The first operand of the operation. +- _`operand2`_ _(Optional)_
+ The second operand of the operation. +- _`operand3`_ _(Optional)_
+The third operand of the operation.
Example: + ```handlebars {{#if (op "===" value1 value2)}}Values are equal{{/if~}}
{{~#op "-" value1}}{{/op~}}
{{~op "?:" value1 "a" "b"}} ``` - Output: +Output: + + ```html Values are equal
-32
a ``` - Preview: +Preview: + 
Values are equal
-32
a
- ### `get` Gets a value from the custom state stack. @@ -351,24 +383,27 @@ Gets a value from the custom state stack.
Syntax: - {{get name}} +{{get name}} - * _`name`_
- The name of the variable to get. +- _`name`_
+The name of the variable to get.
Example: + ```handlebars {{get "some-text"}} ``` - Output: +Output: + + ```html This is the value of some-text! ``` -
+ ### `set` @@ -377,27 +412,30 @@ Assigns a value to the custom state stack.
Syntax: - {{#set name}}value{{/get}}
- {{set name value}}
+{{#set name}}value{{/get}}
+{{set name value}}
- * _`name`_
- The name of the variable to assign. - * _`value`_
- The value of the variable. +- _`name`_
+ The name of the variable to assign. +- _`value`_
+The value of the variable.
Example: + ```handlebars {{#set "some-text"}}This is the value of some-text!{{/set~}} {{~set "some-number" 32}} ``` - Output: +Output: + + ```html ``` -
+ ### `#scope` @@ -408,16 +446,17 @@ and variable lookups will start from the most recent scope and work backwards un
Syntax: - {{#scope}}content{{/scope}} +{{#scope}}content{{/scope}} - * _`name`_
- The name of the variable to assign. - * _`value`_
- The value of the variable. +- _`name`_
+ The name of the variable to assign. +- _`value`_
+The value of the variable.
Example: + ```handlebars {{~set "key" 32~}} {{~get "key"~}}, @@ -429,12 +468,14 @@ and variable lookups will start from the most recent scope and work backwards un {{~get "key"~}} ``` - Output: +Output: + + ```html 32,32,64,32 ``` -
+ ### `property` @@ -443,26 +484,29 @@ Repeatedly gets a property of an object.
Syntax: - {{property object property1 property2 ... propertyN}} +{{property object property1 property2 ... propertyN}} - * _`object`_
- The initial object to use. - * _`propertyN`_
- A chain of property names to get on the object. +- _`object`_
+ The initial object to use. +- _`propertyN`_
+A chain of property names to get on the object.
Example: + ```handlebars {{property someObject "field" 0 "toString"}} ``` - Output: +Output: + + ```html function toString() { [native code] } ``` -
+ ### `noop` @@ -471,21 +515,25 @@ No-op. Returns the inner contents of the template.
Syntax: - {{#noop}}content{{/noop}} +{{#noop}}content{{/noop}} +
Example: + ```handlebars {{noop}}Unchanged content{{/noop}} ``` - Output: +Output: + + ```html Unchanged content ``` -
+ ### `isMoraPitchHigh` @@ -494,21 +542,25 @@ Returns whether or not a mora will have a high pitch, given the index of the mor
Syntax: - {{isMoraPitchHigh index position}} +{{isMoraPitchHigh index position}} +
Example: + ```handlebars {{#if (isMoraPitchHigh 1 2)}}High pitch{{else}}Low pitch{{/if}} ``` - Output: +Output: + + ```html High pitch ``` -
+ ### `getKanaMorae` @@ -517,25 +569,29 @@ Returns an array of the mora for a kana string.
Syntax: - {{getKanaMorae kana-string}} +{{getKanaMorae kana-string}} +
Example: + ```handlebars {{#each (getKanaMorae "よみたん")}}{{{.}}}
{{/each}} ``` - Output: +Output: + + ```html よ
み
た
ん
``` - Preview: +Preview: + 
よ
み
た
ん
- ### `typeof` Returns the type of a value. `#typeof` in the block form will always return `'string'`. @@ -543,29 +599,32 @@ Returns the type of a value. `#typeof` in the block form will always return `'st
Syntax: - {{typeof value}}
- {{#typeof}}value{{/typeof}}
+{{typeof value}}
+{{#typeof}}value{{/typeof}}
- * _`value`_
- The value to check. +- _`value`_
+The value to check.
Example: + ```handlebars {{typeof "よみたん"}} {{typeof 1}} {{#typeof}}よみたん{{/typeof}} ``` - Output: +Output: + + ```html string number string ``` -
+ ### `join` @@ -574,27 +633,30 @@ Joins the arguments to a single string with a separator, flattening any argument
Syntax: - {{join separator value1 value2 valueN...}}
+{{join separator value1 value2 valueN...}}
- * _`separator`_
- The separator string to use between values. - * _`valueN`_
- An individual value to join into the resulting string +- _`separator`_
+ The separator string to use between values. +- _`valueN`_
+An individual value to join into the resulting string
Example: + ```handlebars {{set "index" 32~}} {{~join "_" "yomitan" (get "index") "value"}} ``` - Output: +Output: + + ```html yomitan_32_value ``` -
+ ### `concat` @@ -603,25 +665,28 @@ Joins the arguments to a single string, without flattening arguments that are ar
Syntax: - {{concat value1 value1 valueN...}}
+{{concat value1 value1 valueN...}}
- * _`valueN`_
- A value to join into the resulting string +- _`valueN`_
+A value to join into the resulting string
Example: + ```handlebars {{set "index" 32~}} {{~concat "yomitan_" (get "index") "_value"}} ``` - Output: +Output: + + ```html yomitan_32_value ``` -
+ ### `pitchCategories` @@ -630,24 +695,27 @@ Returns an array representing the different pitch categories for a specific term
Syntax: - {{pitchCategories @root}}
+{{pitchCategories @root}}
- * _`@root`_
- The argument passed should always be the root data object. +- _`@root`_
+The argument passed should always be the root data object.
Example: + ```handlebars [{{#each (pitchCategories @root)}}{{.}}{{#unless @last}}, {{/unless}}{{/each}}] ``` - Output: +Output: + + ```html [heiban, kifuku] ``` -
+ ### `formatGlossary` @@ -657,26 +725,29 @@ structured-content generation.
Syntax: - {{formatGlossary dictionary definitionEntry}}
+{{formatGlossary dictionary definitionEntry}}
- * _`dictionary`_
- The dictionary that the glossary entry belongs to. - * _`definitionEntry`_
- The definition entry object in raw form. +- _`dictionary`_
+ The dictionary that the glossary entry belongs to. +- _`definitionEntry`_
+The definition entry object in raw form.
Example: + ```handlebars {{#each glossary}}{{formatGlossary ../dictionary .}}{{/each}} ``` - Output: +Output: + + ```html Here is the content of a gloss, which may include formatted HTML. ``` -
+ ### `hasMedia` & `getMedia` @@ -686,29 +757,30 @@ These functions are used together in order to request media and other types of o
Syntax: - {{hasMedia type args...}}
- {{getMedia type args... [escape=true|false]}}
+{{hasMedia type args...}}
+{{getMedia type args... [escape=true|false]}}
- * _`type`_
- The type of media to check for. - * _`args`_
- Additional arguments for the media. The arguments depend on the media type. - * _`escape`_ _(optional)_
- Whether or not the resulting text should be HTML-escaped. If omitted, defaults to `true`. +- _`type`_
+ The type of media to check for. +- _`args`_
+ Additional arguments for the media. The arguments depend on the media type. +- _`escape`_ _(optional)_
+ Whether or not the resulting text should be HTML-escaped. If omitted, defaults to `true`. - **Available media types and arguments** +**Available media types and arguments** - * "audio" - * "screenshot" - * "clipboardImage" - * "clipboardText" - * "selectionText" - * "textFurigana" japaneseText readingMode="default|hiragana|katakana" - * "dictionaryMedia" fileName dictionary="Dictionary Name" +- "audio" +- "screenshot" +- "clipboardImage" +- "clipboardText" +- "selectionText" +- "textFurigana" japaneseText readingMode="default|hiragana|katakana" +- "dictionaryMedia" fileName dictionary="Dictionary Name"
Examples: + ```handlebars {{#if (hasMedia "audio")}}The audio file name is: {{getMedia "audio"}}{{/if}} @@ -725,7 +797,9 @@ These functions are used together in order to request media and other types of o {{#if (hasMedia "dictionaryMedia" "image.png" dictionary="Example Dictionary")}}The remapped file name for image.png is: {{getMedia "dictionaryMedia" "image.png" dictionary="Example Dictionary"}}{{/if}} ``` - Output: +Output: + + ```html The audio file name is: yomitan_audio_にほんご_日本語.mp3 @@ -743,8 +817,8 @@ These functions are used together in order to request media and other types of o The remapped file name for image.png is: yomitan_dictionary_media_1_にほんご_日本語.png ``` -
+ ### `pronunciation` @@ -754,30 +828,31 @@ same as the system used for generating popup and search page dictionary entries.
Syntax: - {{pronunciation format=string reading=string downstepPosition=integer [nasalPositions=array] [devoicePositions=array]}}
+{{pronunciation format=string reading=string downstepPosition=integer [nasalPositions=array] [devoicePositions=array]}}
- * _`format`_
- The format of the HTML to generate. This can be any of the following values: - * `'text'` - * `'graph'` - * `'position'` - * _`reading`_
- The kana reading of the term. - * _`downstepPosition`_
- The mora position of the downstep in the reading. - * _`nasalPositions`_ _(optional)_
- An array of indices of mora that have a nasal pronunciation. - * _`devoicePositions`_ _(optional)_
- An array of indices of mora that are devoiced. +- _`format`_
+ The format of the HTML to generate. This can be any of the following values: + - `'text'` + - `'graph'` + - `'position'` +- _`reading`_
+ The kana reading of the term. +- _`downstepPosition`_
+ The mora position of the downstep in the reading. +- _`nasalPositions`_ _(optional)_
+ An array of indices of mora that have a nasal pronunciation. +- _`devoicePositions`_ _(optional)_
+An array of indices of mora that are devoiced.
Example: + ```handlebars {{~pronunciation format='text' reading='よむ' downstepPosition=1~}} ``` -
+ ### `hiragana` @@ -786,18 +861,19 @@ Converts katakana text to hiragana.
Syntax: - {{hiragana value [keepProlongedSoundMarks=true|false]}}
- {{#hiragana [keepProlongedSoundMarks=true|false]}}value{{/hiragana}}
+{{hiragana value [keepProlongedSoundMarks=true|false]}}
+{{#hiragana [keepProlongedSoundMarks=true|false]}}value{{/hiragana}}
- * _`value`_
- The text to convert. - * _`keepProlongedSoundMarks`_ _(optional)_
- Whether or not the `ー` character should be kept or converted to a vowel character. - Defaults to `false` if not specified. +- _`value`_
+ The text to convert. +- _`keepProlongedSoundMarks`_ _(optional)_
+Whether or not the `ー` character should be kept or converted to a vowel character. +Defaults to `false` if not specified.
Example: + ```handlebars {{hiragana "よみたん ヨミたん ヨミタン"}} {{#hiragana}}よみたん ヨミたん ヨミタン{{/hiragana}} @@ -805,15 +881,17 @@ Converts katakana text to hiragana. {{#hiragana keepProlongedSoundMarks=true}}ローマ字{{/hiragana}} ``` - Output: +Output: + + ```html よみたん よみたん よみたん よみたん よみたん よみたん ろうま字 ろーま字 ``` -
+ ### `katakana` @@ -822,23 +900,27 @@ Converts hiragana text to katakana.
Syntax: - {{katakana text}}
- {{#katakana}}text{{/katakana}}
+{{katakana text}}
+{{#katakana}}text{{/katakana}}
- * _`text`_
- The text to convert. +- _`text`_
+The text to convert.
Example: + ```handlebars {{katakana "よみたん ヨミたん ヨミタン"}} {{#katakana}}よみたん ヨミたん ヨミタン{{/katakana}} ``` - Output: +Output: + + ```html ヨミタン ヨミタン ヨミタン ヨミタン ヨミタン ヨミタン ``` +
-- cgit v1.2.3