Changes

8 changed files (+458/-215)

• docs/en/Features/Ambiguous path resolution.md (new)
  • @@ -0,0 +1,71 @@
    + In addition to the normal internal path such as, + + ``` + [Foo](./Foo.md) + ``` + + Obsidian resolves ambiguous path notations too. + This page lists ambiguous path notations Macana supports. + + Macana uses these path resolutions for: + + - Regular Markdown links (`[label](url)`) + - Wikilinks (`[[internal link]]`) + - Regular Markdown images (``) + - Wikilink embeds (`![[internal link]]`) + + ## List of supported ambiguous path resolutions + ### Relative path without file extension + + You can omit the file extension part from the relative path. + However, this would negatively affects build performance due to additional I/O for lookup. + + ```markdown + [Overview](../Overview) + ``` + + [Overview](../Overview) + + ### Absolute path + + If you write absolute path, Macana resolves it from the Vault root (document root). + + ```markdown + [Overview](/en/Overview.md) + ``` + + [Overview](/en/Overview.md) + + ### Absolute path without file extension + + You can omit the file extension part from the absolute path too. + This would also negatively affects build performance. + + ```markdown + [Overview](/en/Overview) + ``` + + [Overview](/en/Overview) + + ### Shortest path when possible + + Macana supports "Shortest path when possible" links, which is the default value for the recent Obsidian versions. + If Macana finds more than one file having the same name as the link target, Macana throws an error and aborts the build. + + ```markdown + [Overview](Overview) + ``` + + [Overview](Overview) + + ## Limitation + + ### Filename confusion on extension-less path + + When you have more than one file with same file stem (file name without file extension including the dot), you can't refer to the file without extension. + + For example, if you have both `Foo/Bar.md` and `Foo/Bar.jpg` on a same directory, below `Foo/Baz.md` results in a build error, because Macana cannot decide which file to use. + + ```markdown + [Bar](./Bar) + ```
• docs/en/Features/JSONCanvas.canvas (new)
  • @@ -0,0 +1,10 @@
    + { + "nodes":[ + {"id":"fcd5e40a9ea08eef","x":340,"y":-410,"width":360,"height":140,"type":"text","text":"# What is JSONCanvas?\nThis. What you are seeing now."}, + {"id":"5ddfb6fb8ebe642f","x":-600,"y":-860,"width":460,"height":370,"color":"5","type":"text","text":"# Text node\nThis is text node.\n\nYou can write text content in Markdown format.\n\n> [!tip]+\n> All of Markdown extensions are also available in text nodes."}, + {"id":"a7c1315325193216","x":-860,"y":-340,"width":420,"height":280,"type":"text","text":"# Supported features\n\n- [x] Text node\n- [x] Group node\n- [x] File node\n- [x] Link node"} + ], + "edges":[ + {"id":"7f28c2f7d51a0012","fromNode":"a7c1315325193216","fromSide":"top","toNode":"5ddfb6fb8ebe642f","toSide":"bottom"} + ] + }
• docs/en/Features/Markdown/CommonMark.md (new)
  • @@ -0,0 +1,93 @@
    + Macana uses [micromark](https://github.com/micromark/micromark) and [mdast](https://github.com/syntax-tree/mdast) utilities for basic Markdown parsing. + Those libraries are based on [CommonMark](https://commonmark.org/), a de-facto standard of Markdown syntax. + Because of that, you can expect Macana to correctly render CommonMark syntax otherwise overridden by extensions. + + - [CommonMark Spec](https://spec.commonmark.org/0.31.2/) (v0.31.2) + + As the number of syntax element is large, this page only lists additional behavior and restrictions performed by Macana. + + ## Heading levels + + Since Macana uses a file name or `title` YAML frontmatter field for `<h1>`, you should avoid using level 1 heading in your Markdown files. + + > [!info] + > There is a plan for adding an option to down-level headings in a future. + > See [[Roadmap]] for more info. + + ## Syntax highlighting + + Add language name as a first word of [info string](https://spec.commonmark.org/0.31.2/#info-string) for a [fenced code block](https://spec.commonmark.org/0.31.2/#fenced-code-blocks) to add syntax highlighting to the code block. + Macana uses [refractor](https://github.com/wooorm/refractor) as a syntax highlight engine. + + > [!info] + > Style customization is not supported yet. + + ~~~markdown + Snippet from JSONCanvas renderer. + + ```tsx + function textNode({ node }: TextNodeProps) { + const containerStyle: StyleConstructor = { + width: node.width, + height: node.height, + }; + + // NOTE: Safari can't render `<foreignObject>` correctly. + // In this case, Safari renders an overflowing element at completely incorrect + // position and size, which makes the element invisible (outside viewport). + // https://github.com/mdn/content/issues/1319 + // https://bugs.webkit.org/show_bug.cgi?id=90738 + // https://bugs.webkit.org/show_bug.cgi?id=23113 + return ( + <foreignObject + x={node.x} + y={node.y} + width={node.width} + height={node.height} + > + <div + xmlns="http://www.w3.org/1999/xhtml" + style={constructStyle(containerStyle)} + class={c.embed} + > + {node.text} + </div> + </foreignObject> + ); + } + ``` + ~~~ + + Snippet from JSONCanvas renderer. + + ```tsx + function textNode({ node }: TextNodeProps) { + const containerStyle: StyleConstructor = { + width: node.width, + height: node.height, + }; + + // NOTE: Safari can't render `<foreignObject>` correctly. + // In this case, Safari renders an overflowing element at completely incorrect + // position and size, which makes the element invisible (outside viewport). + // https://github.com/mdn/content/issues/1319 + // https://bugs.webkit.org/show_bug.cgi?id=90738 + // https://bugs.webkit.org/show_bug.cgi?id=23113 + return ( + <foreignObject + x={node.x} + y={node.y} + width={node.width} + height={node.height} + > + <div + xmlns="http://www.w3.org/1999/xhtml" + style={constructStyle(containerStyle)} + class={c.embed} + > + {node.text} + </div> + </foreignObject> + ); + } + ```
• docs/en/Features/Markdown/GitHub Flavored Markdown.md (new)
  • @@ -0,0 +1,130 @@
    + Obsidian's Markdown dialect, called [[en/Features/Markdown/Obsidian Flavored Markdown|Obsidian Flavored Markdown (OFM)]], is based on another dialect called GitHub Flavored Markdown (GFM). + GFM is based on CommonMark, and has additional syntax extension and undocumented widgets that abuses existing Markdown syntax. + + - [GitHub Flavored Markdown Spec](https://github.github.com/gfm/) + + ## Supported features + + ### Strikethrough + + Surround text with a pair of one or two tildes (`~`) to make the part strikethrough. + + - [Specification](https://github.github.com/gfm/#strikethrough-extension-) + + ```markdown + ~~This text is rendered with strikethrough~~. + ``` + + ~~This text is rendered with strikethrough~~. + + ### Task list items + + Add `[ ]` (unchecked) or `[x]` (checked) before a list item to make it task list item. + + - [Specification](https://github.github.com/gfm/#task-list-items-extension-) + + ```markdown + - [x] Checked + - [ ] Unchecked + - Normal item + - Normal item + - [x] Nested task item + ``` + + - [x] Checked + - [ ] Unchecked + - Normal item + - Normal item + - [x] Nested task item + + ### Footnotes + + This feature is not officially documented at the specification. + + - [Footnotes now supported in Markdown fields - The GitHub Blog](https://github.blog/changelog/2021-09-30-footnotes-now-supported-in-markdown-fields/) + - [Basic writing and formatting syntax - GitHub Docs](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#footnotes) + + ```markdown + This is a normal paragraph[^1]. + + [^1]: I'm not. + ``` + + This is a normal paragraph[^1]. + + [^1]: I'm not. + + ### Autolinks + + Parser treats URL-ish text as a link. + + - [Specification](https://github.github.com/gfm/#autolinks-extension-) + + ```markdown + https://github.github.com/gfm/ + ``` + + https://github.github.com/gfm/ + + ### Tables + + - [Specification](https://github.github.com/gfm/#tables-extension-) + + ```markdown + | Language | Execution | + | :--------: | ----------------- | + | JavaScript | Interpreter & JIT | + ``` + + | Language | Execution | + | :--------: | ----------------- | + | JavaScript | Interpreter & JIT | + | Dart | AOT or JIT | + + ## Unsupported features + + ### Alerts + + This feature is not officially documented at the specification. + + - [Basic writing and formatting syntax - GitHub Docs](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts) + + Syntax-wise, a valid GFM Alert is a valid OFM Callout: <math><mi>Alert</mi><mo>⊂</mo><mi>Callout</mi></math>. + However, the `CAUTION` type will be rendered as same variant as `WARNING` type, as shown below. + + ```markdown + > [!WARNING] + > Urgent info that needs immediate user attention to avoid problems. + + > [!CAUTION] + > Advises about risks or negative outcomes of certain actions. + ``` + + > [!WARNING] + > Urgent info that needs immediate user attention to avoid problems. + + > [!CAUTION] + > Advises about risks or negative outcomes of certain actions. + + ### MermaidJS diagrams + + This feature is not officially documented at the specification. + + - [Creating diagrams - GitHub Docs](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-diagrams) + + Due to the library neither be able to output without headless Chrome/Chromium nor exposes syntax parser, Macana does not support for this feature currently. + + ### Mathematical expressions + + This feature is not officially documented at the specification. + + - [Writing mathematical expressions - GitHub Docs](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/writing-mathematical-expressions) + + OFM defines [its own syntax for mathematical expressions](https://help.obsidian.md/Editing+and+formatting/Advanced+formatting+syntax#Math). + While both OFM and GFM use dollar sign as a marker, GFM also supports an alternative syntax for inline mathematical expression: + + ```markdown + Answer is $`x = 5`$. + ``` + + Macana does not support this alternative syntax.
• docs/en/Features/Markdown/Obsidian Flavored Markdown.md (new)
  • @@ -0,0 +1,154 @@
    + Obsidian's Markdown dialect is called Obsidian Flavored Markdown (OFM). + OFM is based on [[en/Features/Markdown/GitHub Flavored Markdown|GitHub Flavored Markdown (GFM)]], with additions and some deviations. + + Unfortunately, Obsidian does not publish formal specification for OFM. + Due to the lack of specification, Macana's support for OFM is best-effort. + + - [Basic formatting syntax - Obsidian Help](https://help.obsidian.md/Editing+and+formatting/Basic+formatting+syntax) + - [Advanced formatting syntax - Obsidian Help](https://help.obsidian.md/Editing+and+formatting/Advanced+formatting+syntax) + - [Obsidian Flavored Markdown - Obsidian Help](https://help.obsidian.md/Editing+and+formatting/Obsidian+Flavored+Markdown) + + ## Supported features + + ### Wikilinks + + By default, Obsidian uses their own variant of [wikilink](https://en.wikipedia.org/wiki/Help:Link) for internal links. + To use this link style, surround the target file name without file extension or path to the file from the Vault root (document root) without file extension, with `[[` and `]]`. + + - [Internal links - Obsidian Help](https://help.obsidian.md/Linking+notes+and+files/Internal+links) + + ```markdown + - [[Overview|Alternative Title]] + - [[Overview]] + ``` + + - [[Overview|Alternative Title]] + - [[Overview]] + + ### Image size attributes + + Add a vertical pipe (`|`) following text specifying image dimensions to set the image size inside image's alt text. + + - [Basic formatting syntax - Obsidian Help](https://help.obsidian.md/Editing+and+formatting/Basic+formatting+syntax#External+images) + + ```markdown +  + ``` + +  + + ### Embeds + + You can embeds files in [accepted file formats](https://help.obsidian.md/Files+and+folders/Accepted+file+formats) by adding `!` right before the wikilink's opening square brackets. + + - [Embed files - Obsidian Help](https://help.obsidian.md/Linking+notes+and+files/Embed+files) + + #### Images + + To set the display image size, add a vertical pipe (`|`) following text specifying image dimension. + + - [Embed files - Obsidian Help](https://help.obsidian.md/Linking+notes+and+files/Embed+files#Embed+an+image+in+a+note) + + ```markdown + ![[dog.jpg|128x128]] + ``` + + ![[dog.jpg|128x128]] + + ### Highlights + + Surround text with `==` to make the text highlighted. + + - [Basic formatting syntax - Obsidian Help](https://help.obsidian.md/Editing+and+formatting/Basic+formatting+syntax#Bold,%20italics,%20highlights) + + ```markdown + ==Hello, World!== + ``` + + ==Hello, World!== + + ### Callouts + + - [Callouts - Obsidian Help](https://help.obsidian.md/Editing+and+formatting/Callouts) + + ```markdown + > [!info]+ Title, _Italic_ + > Both title and body can contain Markdown. + ``` + + > [!info]+ Title, _Italic_ + > Both title and body can contain Markdown. + + ### Mathematical expressions + + Macana supports mathematical expressions, both inline one (`$`) and block one (`$$`). + + - [Advanced formatting syntax - Obsidian Help](https://help.obsidian.md/Editing+and+formatting/Advanced+formatting+syntax#Math) + + Macana uses [Temml](https://temml.org/) while Obsidian uses [MathJax](https://docs.mathjax.org/en/latest/basic/mathjax.html), in order to support environments without JavaScript. + Possible differences including, but not limited to: + + - Resulting graphics differs (Macana uses standard MathML, Obsidian uses MathJax's SVG output) + - Certain LaTeX macros available on Obsidian but not on Macana and vice versa. + - Rendering differences between User Agents due to rendering engines and/or available fonts. + + ```markdown + This is an inline math expression $e^{2i\pi} = 1$. + ``` + + This is an inline math expression $e^{2i\pi} = 1$. + + ```markdown + $$ + \begin{vmatrix}a & b\\ + c & d + \end{vmatrix}=ad-bc + $$ + ``` + + $$ + \begin{vmatrix}a & b\\ + c & d + \end{vmatrix}=ad-bc + $$ + + ### Comments + + Surround portion of text with `%%` to exclude them from the output HTML. + + - [Basic formatting syntax - Obsidian Help](https://help.obsidian.md/Editing+and+formatting/Basic+formatting+syntax#Comments) + + ```markdown + Foo %%Bar%% Baz + + %% + This entire block + + should not be in the output HTML. + %% + ``` + + Foo %%Bar%% Baz + + %% + This entire block + + should not be in the output HTML. + %% + + ## Unsupported features + + ### Nested callouts + + For a technical reason, Macana currently cannot parse nested callouts. + This example is from Obsidian help document: + + ```markdown + > [!question] Can callouts be nested? + > > [!todo] Yes!, they can. + > > > [!example] You can even use multiple layers of nesting. + ``` + + > [!question] Can callouts be nested? + > > [!todo] Yes!, they can. + > > > [!example] You can even use multiple layers of nesting.
• docs/en/Writing Samples/GitHub Flavored Markdown.md (deleted)
  • @@ -1,60 +0,0 @@
    - --- - createdAt: 2024-04-09T20:30:00+09:00 - updatedAt: 2024-04-13T18:00:00+09:00 - --- - - GitHub Flavored Markdown (GFM) is a Markdown dialect based on CommonMark spec. - This page lists extensions not exist in CommonMark. - - - Spec: https://github.github.com/gfm/ - - ## Strikethrough extension - - ```markdown - ~~This text is rendered with strikethrough~~. - ``` - - ~~This text is rendered with strikethrough~~. - - ## Task Lists extension - - ```markdown - - [x] Checked - - [ ] Unchecked - ``` - - - [x] Checked - - [ ] Unchecked - - ## Footnotes extension - - ```markdown - This is a normal paragraph[^1]. - - [^1]: I'm not. - ``` - - This is a normal paragraph[^1]. - - [^1]: I'm not. - - ## Autolinks extension - - ```markdown - https://github.github.com/gfm/ - ``` - - https://github.github.com/gfm/ - - ## Tables extension - - ```markdown - | Language | Execution | - | :--------: | ----------------- | - | JavaScript | Interpreter & JIT | - ``` - - | Language | Execution | - | :--------: | ----------------- | - | JavaScript | Interpreter & JIT | - | Dart | AOT or JIT |
• docs/en/Writing Samples/Obsidian Flavored Markdown.md (deleted)
  • @@ -1,85 +0,0 @@
    - --- - createdAt: 2024-04-09T21:00:00+09:00 - updatedAt: 2024-04-18T07:35:00+09:00 - --- - - Obsidian Flavored Markdown (OFM) is an authoring format used in Obsidian, based on CommonMark and [[GitHub Flavored Markdown]] (GFM). - This page lists extensions not exists in both CommonMark and GFM. - - - [Obsidian Flavored Markdown - Obsidian Help](https://help.obsidian.md/Editing+and+formatting/Obsidian+Flavored+Markdown) - - [Basic formatting syntax - Obsidian Help](https://help.obsidian.md/Editing+and+formatting/Basic+formatting+syntax) - - [Advanced formatting syntax - Obsidian Help](https://help.obsidian.md/Editing+and+formatting/Advanced+formatting+syntax) - - Unfortunately, Obsidian does not publish a formal spec for the OFM. - Users should be aware Macana's OFM parser is not guaranteed to be 100% compatible with Obsidian's one, as the spec is not defined and even Obsidian behave inconsistent in some area. - - ## Wikilink extension - - ```markdown - - [[GitHub Flavored Markdown|GFM]] - - [[Overview]] - ``` - - - [[GitHub Flavored Markdown|GFM]] - - [[Overview]] - - Document embedding is not supported yet. - - ## Highlight extension - - ```markdown - ==Hello, World!== - ``` - - ==Hello, World!== - - ## Callout extension - - ```markdown - > [!info]+ Title, [[GitHub Flavored Markdown]] - > Both title and body can contain Markdown. - ``` - - > [!info]+ Title, [[GitHub Flavored Markdown]] - > Both title and body can contain Markdown. - - ## Image size attribute - - OFM abuses image `alt` slot for size specifier. - You can inspect the `<img>` tags below to see how it affects the resulting markup. - - ```markdown -  -  -  - ![[dog.jpg|64]] - ``` - -  -  -  - ![[dog.jpg|64]] - - ## Math extension (LaTeX) - - Macana parses math notations using [Temml](https://temml.org/). It converts LaTeX notation to MathML, which browsers natively support without JavaScript. - - ```markdown - This is an inline math expression $e^{2i\pi} = 1$. - ``` - - This is an inline math expression $e^{2i\pi} = 1$. - - ```markdown - $$ - \begin{vmatrix}a & b\\ - c & d - \end{vmatrix}=ad-bc - $$ - ``` - - $$ - \begin{vmatrix}a & b\\ - c & d - \end{vmatrix}=ad-bc - $$
• docs/en/Writing Samples/Path resolution.md (deleted)
  • @@ -1,70 +0,0 @@
    - --- - createdAt: 2024-04-15T23:00:00+09:00 - updatedAt: 2024-04-15T23:00:00+09:00 - --- - - ## Supported path resolutions - ### Relative - - Relative link is the best format, especially if you consider compatibility to other tools. - - ```markdown - [Overview](../Overview.md) - ``` - - [Overview](../Overview.md) - - #### Without file extension - - Although you can omit file extensions in the file path, this is not recommended if you care compatibility or portability. - This also affects performance. - - ```markdown - [Overview](../Overview) - ``` - - [Overview](../Overview) - - ### Absolute - - Absolute paths are resolved from the Vault root. - - ```markdown - [Overview](/en/Overview.md) - ``` - - [Overview](/en/Overview.md) - - #### Without file extension - - You can omit file extensions in the absolute form, too. - This affects performance. - - ```markdown - [Overview](/en/Overview) - ``` - - [Overview](/en/Overview) - - ### Shortest path when possible - - Macana also supports "Shortest path when possible" links, which is the default value for the newer Obsidian versions. - When Vault has more than one file having same name, resolution will result in error. - - ```markdown - [Overview](Overview) - ``` - - [Overview](Overview) - - ## Limitation - - ### Filename confusion on extension-less path - - When you have more than one file with same file stem (filename without extension part), you can't refer to the file without extension. - - For example, if you have both `Foo/Bar.md` and `Foo/Bar.jpg` on a same directory, below `Foo/Baz.md` results in a build error, because Macana cannot decide which file to use. - - ```markdown - [Bar](./Bar) - ```