diff --git a/README.md b/README.md index 1526736..cdb3047 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ Everything about note management. All in Zotero. -Better Notes Handbook: [EN](https://github.com/windingwind/zotero-better-notes/wiki) | [δΈ­ζ–‡ (provide translation)](https://zotero.yuque.com/staff-gkhviy/better-notes/biigg4?) +Better Notes Handbook (out dated, for version<=0.8.9): [δΈ­ζ–‡ (provide translation)](https://zotero.yuque.com/staff-gkhviy/better-notes/biigg4?) ## 🧩 Outline @@ -157,9 +157,13 @@ _Note Template_ is designed for tasks like: - Compare papers across sections - Generate content programmatically -> πŸ’‘ Want to write your own templates? [Learn more β†’](#note-link) +> πŸ’‘ Need help or looking for community templates?[See here β†’](https://github.com/windingwind/zotero-better-notes/discussions/categories/note-templates) > -> πŸ’‘ Need help or looking for community templates?[Learn more β†’](#note-link) +> πŸ’‘ Want to write/share your own templates? +> +> [How to write β†’](docs/about-note-template.md#write-note-template) +> +> [How to share β†’](docs/about-note-template.md#share-your-template)
diff --git a/docs/about-note-template.md b/docs/about-note-template.md new file mode 100644 index 0000000..a065e7c --- /dev/null +++ b/docs/about-note-template.md @@ -0,0 +1,388 @@ +# Use Note Template + +You can search and find note templates from the community [here](https://github.com/windingwind/zotero-better-notes/discussions/categories/note-templates). + +## Import Note Template + +One-click to import. + +1. Copy the template below (just an example). +
+Click to show the example template + +```yaml +name: "[Text] Current Time" +content: |- + // @use-markdown + // @author windingwind + // @link https://github.com/windingwind/zotero-better-notes/blob/master/docs/about-note-template.md + + # Template Example: Current Time + + > Author: windingwind + > + > from: [GitHub-Zotero Better Notes: Write Note Template](https://github.com/windingwind/zotero-better-notes/blob/master/docs/about-note-template.md) + + **Current Time**: ${new Date().toLocaleString()} +``` + +
+ +2. Goto Zotero menubar, click `Edit`->`New Template from Clipboard`. +3. Click OK. + +Now you can open a note/the workspace and in editor toolbar, click `Insert Template to cursor line`. Select the template, it is inserted to the note. + +# Write Note Template + +## What is this? + +This section aims to help you writing a note template of Better Notes. See [here](../README.md#note-template) for the introduction of the note template. + +Use [Markdown](https://www.markdownguide.org/cheat-sheet/)/[HTML](https://developer.mozilla.org/en-US/docs/Web/HTML) to write a note template. If you want to execute scripts in the template, you may want to use [JavaScript](https://developer.mozilla.org/en-US/docs/Web/JavaScript). + +> πŸ’‘It's OK if you don't know them. Creating your own template is very easy! + +## Overview + +- [Note Template Structure](#note-template-structure) +- [Pragma](#pragma) +- [Script in Note Template](#script-in-note-template) +- [Template Type](#template-type) +- [Style Syntax](#style-syntax) +- [Script Syntax](#script-syntax) +- [Share Your Template](#share-your-template) + +## Note Template Structure + +A template consists of two parts: + +**Name**: The name of template. starts with `[TYPE]`, where the `TYPE` should be the actual type of the template, e.g. `Item`, `Text`, etc. + +**Content**: The template code. + +## Pragma + +Pragmas are lines start with `// @`. They have special effect and will not be rendered. + +### `// @use-markdown` + +Let the compiler know you are using markdown. Otherwise the template will be processed as HTML. + +### `// @author` + +Mark the code belongs to you. Your GitHub account or your email. + +### `// @link` + +Link to the page where the template is published so that users can contact you and give feedback. + +### `// @${stage}-begin` and `// @${stage}-end` + +The `Item` template supports three stages and others only support `default` stage. + +If not specified, the whole template will be recognized as `default`. + +Code wrapped by `// @${stage}-begin` and `// @${stage}-end` will be processed during the corresponding stage. Here the `${stage}` should be replaced by the actual stage name, like `beforeloop`. + +## Script in Note Template + +Note template supports JavaScript. Wrap them with `${code here}`. The example in [Import Note Template](#import-note-template) uses `${new Date().toLocaleString()}` to render the current time. + +Each template has its own global variables. See [Template Type](#template-type) for more information. + +All templates share a global variable `_env = {dryRun: boolean}`. In preview mode (in template editor), the `_env.dryRun` is `true` and in that case you must not modify the library. + +> πŸ’‘How to run async code? +> Wrap them in an async function call: +> +> ```js +> ${ +> await new Promise(async (resolve) => { +> // execute async code here +> const returnString = await something(); +> // return a string as the rendering result: +> resolve(returnString); +> }); +> } +> ``` + +## Template Type + +### Item + +Process one or more item(s). The input items are from the item picker window or the selected items. + +There are three stages (`beforeloop`, `default`, `afterloop`) in this template. Use pragmas to wrap the template code to indicate on which stage it should be processed. + +If no stage pragma is given, the whole template will be processed on the default stage. + +
+Click to show the example template + +```yaml +name: "[Item] Example Item Template" +content: |- + // @beforeloop-begin + // @use-markdown + # Hi! This only renders once + // @beforeloop-end + // @default-begin +

Title: ${topItem.getField("title")}

+ // @default-end + // @afterloop-begin + > Done! But Markdown is not rendered correctly. Try to add + \`// @use-markdown\` pragma before this line. + // @afterloop-end +``` + +
+ +**Stages and Global Variables** + +`beforeloop` stage: +Processed before loop. + +- items: an array of Zotero item, the input +- targetNoteItem: The note item that accepts the rendered template. Undefined in preview mode (`_env.dryRun` is `true`) +- copyNoteImage: a function that accepts a Zotero item. If the rendered result contains contents from another note, you should call `copyNoteImage(anotherNote)` to copy images from `anotherNote`. +- sharedObj: for temporary variables, shared between all stages + +`default` stage: +Processed in a loop of input items. Run once for each item. + +- topItem: Current item +- targetNoteItem +- itemNotes: The child notes of current item (Deprecated) +- copyNoteImage +- sharedObj + +`afterloop` stage: +Processed after loop. + +- items +- targetNoteItem +- copyNoteImage +- sharedObj + +### Text + +Basic user template. + +**Global Variables** + +- targetNoteItem +- sharedObj + +### Builtin Templates + +| Name | Description | Variables | +| ------------------ | -------------------------------------------------------- | ------------------------------------- | +| QuickInsert | For forward link. | link, linkText, subNoteItem, noteItem | +| QuickBackLink | For back link. | link, linkText, subNoteItem, noteItem | +| QuickImport | For importing note link content. | link, noteItem | +| QuickNote | For generating note from annotation. | annotationItem, topItem, noteItem | +| ExportMDFileName | For generating Markdown file name when exporting. | noteItem | +| ExportMDFileHeader | For generating Markdown file yaml header when exporting. | noteItem | + +## Style Syntax + +We recommend using Markdown for styles. + +| Element | Markdown Syntax | +| ------------------------------------------------------------------------------- | ------------------------------------------------------------- | +| [Heading](https://www.markdownguide.org/basic-syntax/#headings) | `# H1`
`## H2`
`### H3` | +| [Bold](https://www.markdownguide.org/basic-syntax/#bold) | `**bold text**` | +| [Italic](https://www.markdownguide.org/basic-syntax/#italic) | `*italicized text*` | +| Underline | `Underline Text` | +| Strike Trough | `~~Deleted Text~~` | +| Superscript | `N/m2` | +| Subscript | `xi` | +| [Blockquote](https://www.markdownguide.org/basic-syntax/#blockquotes-1) | `> blockquote` | +| [Ordered List](https://www.markdownguide.org/basic-syntax/#ordered-lists) | `1. First item`
`2. Second item`
`3. Third item` | +| [Unordered List](https://www.markdownguide.org/basic-syntax/#unordered-lists) | `- First item`
`- Second item`
`- Third item` | +| [Code](https://www.markdownguide.org/basic-syntax/#code) | `` `code` `` | +| Code Block (Monospaced) | ` ``` `
`function add(x)`
`{return x+1}`
` ``` ` | +| [Horizontal Rule](https://www.markdownguide.org/basic-syntax/#horizontal-rules) | `---` | +| [Link](https://www.markdownguide.org/basic-syntax/#links) | `[title](https://www.example.com)` | +| Highlight Text | `highlighted` | +| Text Color | `colored` | +| Math Inline | `$y=x^2$` | +| Math Block | `$$y=x^2$$` | + +## Script Syntax + +JS scripts are supported. Here are some helpful script snippets. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ScriptScope
Get array of tags from current item + +```js +${topItem.getTags().map(tagObj=>tagObj.tag)}` +``` + +Item:default
Get title of current item + +```js +${topItem.getField("title")} +``` + +Item:default
Get authors of current item + +```js +${topItem.getCreators().map((au) => au.firstName + " " + au.lastName).join("; ")} +``` + +Item:default
Get PDF link of current item + +
+Click to show + +```js +${await new Promise(async (resolve) => { + async function getPDFLink(item) { + const att = await item.getBestAttachment(); + if (!att || !att.isPDFAttachment()) { + return ""; + } + key = att.key; + if (att.libraryID === 1) { + return `zotero://open-pdf/library/items/${key}`; + } else { + groupID = Zotero.Libraries.get(att.libraryID).id; + return `zotero://open-pdf/groups/${groupID}/items/${key}`; + } + } + resolve(await getPDFLink(topItem)); +})} +``` + +
+ +		Item:default
Get (author, year) with PDF link of current item + +
+Click to show + +```js +${await new Promise(async (resolve) => { + const creators = topItem.getCreators(); + let content = ""; + const year = topItem.getField("year"); + if (creators.length === 0) { + content = "no author"; + } else if (creators.length === 1) { + content = `${creators[0].lastName}, ${year}`; + } else { + content = `${creators[0].lastName} etal., ${year}`; + } + // The getPDFLink is from above + const link = await getPDFLink(topItem); + let str = `${content}`; + resolve(str); +})} +``` + +
+ +		Item:default
Get pub date of current item + +```js +${topItem.getField("date")} +``` + +Item:default
Get DOI of current item + +```js +[${topItem.getField("DOI")}]("https://doi.org/${topItem.getField('DOI')}") +``` + +Item:default
Get other fields of current item + +```js +${topItem.getField("FIELD_KEY")} +``` + +`FIELD_KEY` can be found here: https://aurimasv.github.io/z2csl/typeMap.xml + +Item:default
Get CitationKey of current item + +```js +${topItem.citationKey ? topItem.citationKey : ""} +``` + +Item:default
+ +## Share Your Template + +Users can use [Import Note Template](#import-note-template) to copy and import the published templates. + +A template snippet should be in YAML format (YAML has better support for multi-line content): + +```yaml +name: "[TYPE] TEMPLATE NAME" +content: |- + // @author YOUR NAME + // @link PUBLISH PAGE URL + TEMPLATE CONTENT HERE +``` + +or JSON format: + +```json +{ + "name": "[TYPE] TEMPLATE NAME", + "content": "// @author YOUR NAME\n// @link PUBLISH PAGE URL\nTEMPLATE CONTENT HERE" +} +``` + +All templates should be posted [here](https://github.com/windingwind/zotero-better-notes/discussions/categories/note-templates) diff --git a/src/modules/template/editorWindow.ts b/src/modules/template/editorWindow.ts index 282fa03..278ddb0 100644 --- a/src/modules/template/editorWindow.ts +++ b/src/modules/template/editorWindow.ts @@ -88,7 +88,7 @@ export async function showTemplateEditor() { }); _window.document.querySelector("#help")?.addEventListener("click", (ev) => { Zotero.launchURL( - "https://github.com/windingwind/zotero-better-notes/blob/master/Template.md" + "https://github.com/windingwind/zotero-better-notes/blob/master/docs/about-note-template.md" ); }); _window.document.querySelector("#more")?.addEventListener("click", (ev) => {