docs: leverage callouts wherever appropriate

srid · Dec 5, 2023 · 857688b · 857688b
1 parent 7a6150a
commit 857688b
Show file tree

Hide file tree

Showing 10 changed files with 52 additions and 32 deletions.
diff --git a/docs/guide/feed.md b/docs/guide/feed.md
@@ -17,6 +17,9 @@ path:blog/*
 
 If the note is named `blog.md`, then the feed will be available at `blog.xml`.
 
+> [!note] `feed.siteUrl`
+> You must set `feed.siteUrl` (see below) in the [[yaml-config|index.yaml]] for the feed to be generated.
+
 ## Example
 
 An example is available in the [[query]] note. You can access its feed at [query.xml](query.xml).

diff --git a/docs/guide/html-template/neuron-layout.md b/docs/guide/html-template/neuron-layout.md
@@ -12,4 +12,7 @@ template:
   name: /templates/layouts/note
 ```
 
-The "note" layout includes the [[uptree]] of Neuron based on folgezettel links as well as directory layout. Note that all top-level notes are automatically made a folgezettel branch of the root note (index), such that the "home" link appears on top in the uplink tree of all notes. As a demo, the page you are viewing is rendered using the "note" layout (whilst leaving the rest of the site to use the default "book" layout.)
+The "note" layout includes the [[uptree]] of Neuron based on folgezettel links as well as directory layout. Note that all top-level notes are automatically made a folgezettel branch of the root note (index), such that the "home" link appears on top in the uplink tree of all notes. 
+
+> [!tip] Demo
+> As a demo, the very page you are viewing is rendered using the "note" layout (whilst leaving the rest of the site to use the default "book" layout.)
diff --git a/docs/guide/lua-filters.md b/docs/guide/lua-filters.md
@@ -8,7 +8,8 @@ pandoc:
 
 **WARNING**: This is an ==🧪 experimental 🧪== feature and may change in future. It is being made available so users can try it out and give feedback to the author.
 
-See https://github.com/srid/emanote/issues/263
+> [!tip] Progress
+> See https://github.com/srid/emanote/issues/263
 
 To enable a [Pandoc Lua filter](https://pandoc.org/lua-filters.html) for a particular Markdown file, put that filter in your notebook and add the following to the Markdown file's YAML frontmatter:
 
@@ -18,7 +19,8 @@ pandoc:
     - path/to/your.lua
 ```
 
-See [here](https://github.com/srid/emanote/pull/278#issue-1207537343) for known limitations.
+> [!warning] Limitations
+> See [here](https://github.com/srid/emanote/pull/278#issue-1207537343) for known limitations.
 
 ## Demo
 

diff --git a/docs/guide/markdown.md b/docs/guide/markdown.md
@@ -153,6 +153,8 @@ Emanote supports [Obsidian-style callouts](https://help.obsidian.md/Editing+and+
 >
 > Lorem **ipsum** dolor sit *amet*, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
 
+Callouts also work with [[orgmode]] syntax.
+
 ## More extensions
 
 :::{.flex-row .space-y-8}

diff --git a/docs/guide/markdown/custom-style.md b/docs/guide/markdown/custom-style.md
@@ -58,11 +58,8 @@ styling, you can copy the [pandoc.tpl](https://github.com/srid/emanote/blob/mast
 file from Emanote's GitHub repository into your templates/components directory and edit it
 accordingly.
 
-This customization process works through a "union" of the default layer (provided by
-Emanote) and your notebook's layer. Essentially, it's similar to the `unionfs` concept -
-both the default layer and your notebook are union-mounted in Haskell using
-[srid/unionmount](https://github.com/srid/unionmount). This way, you only need to copy and
-modify the specific files you want to override, without affecting the rest of the default templates.
+> [!info] How it works
+> This customization process works through a "union" of the default layer (provided by Emanote) and your notebook's layer. Essentially, it's similar to the `unionfs` concept - both the default layer and your notebook are union-mounted in Haskell using [srid/unionmount](https://github.com/srid/unionmount). This way, you only need to copy and modify the specific files you want to override, without affecting the rest of the default templates.
 
 Several users have successfully implemented this customization approach in their projects.
 Refer to the following examples for inspiration:

diff --git a/docs/guide/markdown/embed.md b/docs/guide/markdown/embed.md
@@ -7,7 +7,8 @@ date: 2022-08-03
 
 You can embed files, using `![[..]]` - a syntax inspired by [Obsidian](https://help.obsidian.md/Linking+notes+and+files/Embedding+files). The HTML can be fully customized for each embed types.
 
-Note that the embed wiki-link syntax must appear on a paragraph of its own, with no other text added next to it.[^blk] Recursive embeds are supported.
+> [!warning] 
+> The embed wiki-link syntax must appear on a paragraph of its own, with no other text added next to it.[^blk] Recursive embeds are supported.
 
 [^blk]: This constraint is necessary to ensure that the HTML generated remains valid. Embedded content use block elements, which cannot be embedded inside inline nodes.
 
@@ -22,10 +23,15 @@ Embedding a note will simply inline it. For example, using `![[start]]` displays
 
 Embedding of [[file-links]], as indicated in the aforementioned Obsidian help page, will eventually be supported; for now, certain file types already work.
 
-See https://github.com/srid/emanote/issues/24 for progress.
+> [!tip] Progress
+> See https://github.com/srid/emanote/issues/24 for progress on this feature.
+
 ### Images
 
-Embedding image files as, say, `![[disaster-girl.jpg]]` is equivalent to `![](path/to/disaster-girl.jpg)` (this example links to [[disaster-girl.jpg|this image]]).  See also the tip: [[adding-images]].
+Embedding image files as, say, `![[disaster-girl.jpg]]` is equivalent to `![](path/to/disaster-girl.jpg)` (this example links to [[disaster-girl.jpg|this image]]).  
+
+> [!tip] See also 
+> [[adding-images]].
 
 [![[disaster-girl.jpg]]](https://knowyourmeme.com/memes/disaster-girl)
 
@@ -78,6 +84,7 @@ The following file extensions are currently supported:
 - `.php`
 - `.c`
 
-To include a new one please see [here](https://github.com/srid/emanote/pull/444). Please
-note that the wrong syntax highlighting might be applied if you are on Firefox
-due to what appears to be a browser bug.
+To include a new one please see [here](https://github.com/srid/emanote/pull/444). 
+
+> [!warning] Firefox users
+> Please note that the wrong syntax highlighting might be applied if you are on Firefox due to what appears to be a browser bug.
diff --git a/docs/guide/orgmode.org b/docs/guide/orgmode.org
@@ -2,7 +2,10 @@
 
 Emanote provides first-class support for [[file:markdown.md][Markdown]]. But it also supports secondary formats (albeit not necessarily with the same level of support) beginning with [[https://orgmode.org/][Org Mode]]. See Pandoc's [[https://pandoc.org/org.html][Org section]] for information on controlling the parsing.
 
-**WARNING**: This is a =🧪 beta 🧪= feature.
+#+BEGIN_QUOTE
+[!warning]
+This is a =🧪 beta 🧪= feature.
+#+END_QUOTE
 
 ** Linking
 Org Mode has no notion of wiki-links, but you can use =file:= [[https://orgmode.org/guide/Hyperlinks.html][hyperlinks]] to link to other files such as Markdown files. If you wish to link to a .org file from a Markdown file, however, regular wiki-links ought to work.

diff --git a/docs/guide/query.md b/docs/guide/query.md
@@ -7,7 +7,10 @@ feed:
 
 # Obsidian-style queries
 
-Emanote supports [Obsidian-style embed queries](https://help.obsidian.md/Plugins/Search#Embed+search+results+in+a+note). See [\#10](https://github.com/srid/emanote/issues/10) for details.
+Emanote supports [Obsidian-style embed queries](https://help.obsidian.md/Plugins/Search#Embed+search+results+in+a+note). 
+
+> [!tip] Progress
+> See [\#10](https://github.com/srid/emanote/issues/10) for details.
 
 Both `*` and `**` are supported in the path patterns. See [System.FilePattern](https://hackage.haskell.org/package/filepattern-0.1.3/docs/System-FilePattern.html) for exact semantics.
 

diff --git a/docs/tips/adding-images.md b/docs/tips/adding-images.md
@@ -1,8 +1,7 @@
 # Adding Images
 
-:::{.note}
-Note that the extension uses the traditional `![]()` syntax to link to the image, but you may switch to using the [[embed|wiki-link embedding syntax]] (`![[]]`) as it has the advantage of not needing to specify the full path to the image (thus allowing you to the move the image around under the notebook without breaking referring links). [[emanote-template]] is already configured to do this by default.
-:::
+>[!tip]
+> The extension uses the traditional `![]()` syntax to link to the image, but you may switch to using the [[embed|wiki-link embedding syntax]] (`![[]]`) as it has the advantage of not needing to specify the full path to the image (thus allowing you to the move the image around under the notebook without breaking referring links). [[emanote-template]] is already configured to do this by default.
 
 If your image is already copied in the OS clipboard---many screenshoting tools[^scr] already provide this capability---and if you use [[vscode]], you can use the [Paste Image](https://marketplace.visualstudio.com/items?itemName=mushan.vscode-paste-image) extension to *directly paste* it in your Markdown note. This does the following,
 

diff --git a/docs/tips/js/syntax-highlighting.md b/docs/tips/js/syntax-highlighting.md
@@ -14,18 +14,19 @@ page:
     <snippet var="js.highlightjs" />
 ```
 
-Bear in mind that when using highlight.js you must manually add language support. The above snippet includes Haskell and Nix by default; otherwise, it is normally added as:
-
-```yaml
-page:
-  headHtml: |
-    <snippet var="js.highlightjs" />
-    <with var="js">
-    <script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/${value:highlightjs-ver}/languages/haskell.min.js"></script>
-    </with>
-```
-
-(The `highlightjs-ver` variable comes from the default [`index.yaml`](https://github.com/srid/emanote/blob/master/emanote/default/index.yaml).)
+> [!warning] 
+> Bear in mind that when using highlight.js you must manually add language support. The above snippet includes Haskell and [Nix](https://nixos.asia) by default; otherwise, it is normally added as:
+>
+> ```yaml
+> page:
+>   headHtml: |
+>     <snippet var="js.highlightjs" />
+>     <with var="js">
+>     <script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/${value:highlightjs-ver}/languages/haskell.min.js"></script>
+>     </with>
+> ```
+> 
+> (The `highlightjs-ver` variable comes from the default [`index.yaml`](https://github.com/srid/emanote/blob/master/emanote/default/index.yaml).)
 
 ## Example (highlight.js)
 
@@ -59,4 +60,4 @@ page:
     <snippet var="js.prism" />
 ```
 
-However, take note that Prism does not cooperate well with Emanote's live preview mode.
+> [!warning] Prism does not cooperate well with Emanote's live preview mode.