From 5222e874f80c62616e462754bbdba992ba0e4d35 Mon Sep 17 00:00:00 2001 From: Zef Hemel Date: Thu, 25 Jan 2024 16:05:48 +0100 Subject: [PATCH] Header docs --- plugs/index/header.ts | 4 ++-- plugs/index/tags.ts | 2 +- website/CHANGELOG.md | 8 +++++--- website/Links.md | 14 ++++++++++++++ website/Manual.md | 1 + website/Markdown/Extensions.md | 2 +- website/Objects.md | 26 +++++++++++++------------- website/Tags.md | 2 +- 8 files changed, 38 insertions(+), 21 deletions(-) create mode 100644 website/Links.md diff --git a/plugs/index/header.ts b/plugs/index/header.ts index 2adf33b..c8bef99 100644 --- a/plugs/index/header.ts +++ b/plugs/index/header.ts @@ -28,12 +28,12 @@ export async function indexHeaders({ name: pageName, tree }: IndexTreeEvent) { }); }, ); - console.log("Found", headers.length, "headers(s)"); + // console.log("Found", headers.length, "headers(s)"); await indexObjects(pageName, headers); } export async function headerComplete(completeEvent: CompleteEvent) { - const match = /\[\[([^\]$:#]*#.*)$/.exec( + const match = /\[\[([^\]$:#]*#[^\]]*)$/.exec( completeEvent.linePrefix, ); if (!match) { diff --git a/plugs/index/tags.ts b/plugs/index/tags.ts index 9784192..6cd19d0 100644 --- a/plugs/index/tags.ts +++ b/plugs/index/tags.ts @@ -59,7 +59,7 @@ export async function tagComplete(completeEvent: CompleteEvent) { return null; } - const match = /#[^#\s]+$/.exec(completeEvent.linePrefix); + const match = /#[^#\d\s\[\]]+\w*$/.exec(completeEvent.linePrefix); if (!match) { return null; } diff --git a/website/CHANGELOG.md b/website/CHANGELOG.md index 6b90435..5d526df 100644 --- a/website/CHANGELOG.md +++ b/website/CHANGELOG.md @@ -4,10 +4,12 @@ release. --- ## Edge +$edge _The changes below are not yet released “properly”. To them out early, check out [the docs on edge](https://community.silverbullet.md/t/living-on-the-edge-builds/27)._ * Tag pages: when you click on a #tag you will now be directed to a page that shows all pages, tasks, items and paragraphs tagged with that tag. * Action buttons (top right buttons) can now be configured, see [[SETTINGS]] how to do this. +* Headers are now indexed, meaning you can query them [[Objects#header]] and also reference them by name via page links using `#` that I just demonstrated 👈. See [[Links]] for more information on all the type of link formats that SilverBullet now supports. * Bug fixes: * Improved Ctrl/Cmd-click (to open links in a new window) behavior: now actually follow `@pos` and `$anchor` links. * Right-clicking links now opens browser native context menu again @@ -35,7 +37,7 @@ _The changes below are not yet released “properly”. To them out early, check * Every object now has a `tag` attribute, signifying the “main” tag for that object (e.g. `page`, `item`) * The `tags` attribute will now _only_ contain explicitly assigned tags (so not the built-in tag, which moved to `tag`) * The new `itags` attribute (available in many objects) includes both the `tag`, `tags` as well as any tags inherited from the page the object appears in. - * Page tags now no longer need to appear at the top of the page, but can appear anywhere as long as they are the only thing appearing in a paragraph with no additional text, see [[Objects$page]]. + * Page tags now no longer need to appear at the top of the page, but can appear anywhere as long as they are the only thing appearing in a paragraph with no additional text, see [[Objects#page]]. * New [[Markdown/Code Widgets|Code Widget]]: `toc` to manually include a [[Table of Contents]] * Filter list (used by [[Page Picker]], [[Template Picker]] and [[Command Palette]]) improvements: * Better ranking @@ -123,8 +125,8 @@ _The changes below are not yet released “properly”. To them out early, check --- ## 0.5.3 * Changes to [[Objects]]: - * Paragraphs are now indexed, see [[Objects$paragraph]] (thanks to [Ian Shehadeh](https://github.com/silverbulletmd/silverbullet/pull/528)) - * For consistency, list items are now always indexed as well (whether they contain a [[Tags|tag]] or not) see [[Objects$item]]. + * Paragraphs are now indexed, see [[Objects#paragraph]] (thanks to [Ian Shehadeh](https://github.com/silverbulletmd/silverbullet/pull/528)) + * For consistency, list items are now always indexed as well (whether they contain a [[Tags|tag]] or not) see [[Objects#item]]. * The {[Directive: Convert to Live Query/Template]} now also converts `#use` and `#include` directives * Styling improvements for Linked Mentions * SilverBullet now fully works when added as PWA on Safari 17 (via the “Add to Dock” option). diff --git a/website/Links.md b/website/Links.md new file mode 100644 index 0000000..bb0589b --- /dev/null +++ b/website/Links.md @@ -0,0 +1,14 @@ +You can create three types of links in SilverBullet: + +* External links, using the `[title](URL)` syntax, for instance: [SilverBullet community](https://community.silverbullet.md). +* “Naked” URL links, like https://community.silverbullet.md +* Internal links using the `[[page name]]` syntax + +# Internal link format +Internal links have different formats: + +* `[[CHANGELOG]]`: a simple link to another page that appears like this: [[CHANGELOG]]. +* `[[CHANGELOG|The Change Log]]`: a link with an alias that appears like this: [[CHANGELOG|The Change Log]]. +* `[[CHANGELOG$edge]]`: a link referencing a particular [[Anchors|anchor]]: [[CHANGELOG$edge]]. +* `[[CHANGELOG#Edge]]`: a link referencing a particular header: [[CHANGELOG#Edge]] +* `[[CHANGELOG@1234]]`: a link referencing a particular position in a page (characters from the start of the document). This notation is generally automatically generated through templates. diff --git a/website/Manual.md b/website/Manual.md index da607ed..2518b08 100644 --- a/website/Manual.md +++ b/website/Manual.md @@ -39,6 +39,7 @@ These are the core concepts used in SilverBullet: * Content is written using [[Markdown]] and rendered using [[Live Preview]] * Markdown [[Markdown/Basics]] * Markdown [[Markdown/Extensions]] + * [[Links]] * [[Markdown/Admonitions]] * [[Plugs/Tasks]] * [[Markdown/Syntax Highlighting]] diff --git a/website/Markdown/Extensions.md b/website/Markdown/Extensions.md index 5727e48..90fc394 100644 --- a/website/Markdown/Extensions.md +++ b/website/Markdown/Extensions.md @@ -1,6 +1,6 @@ In addition to supporting [[Markdown/Basics|markdown basics]] as standardized by [CommonMark](https://commonmark.org/), SilverBullet relies on the following extensions: -* Double-bracketed wiki links: `[[link to page]]`, optionally with aliases `[[link to page|alias]]`. +* [[Links]] * [[Frontmatter]] and [[Attributes]] * [Fenced code blocks](https://www.markdownguide.org/extended-syntax/#fenced-code-blocks), and in addition, assigning new meanings to specific fenced code block languages: * Generically via [[Markdown/Code Widgets]] diff --git a/website/Objects.md b/website/Objects.md index aaf7e7d..7934787 100644 --- a/website/Objects.md +++ b/website/Objects.md @@ -16,13 +16,13 @@ In addition, many objects will also contain: Beside these, any number of additional tag-specific and custom [[Attributes]] can be defined (see below). # Tags -$tags + +tags Every object has a main `tag`, which signifies the type of object being described. In addition, any number of additional tags can be assigned as well via the `tags` attribute. You can use either the main `tag` or any of the `tags` as query sources in [[Live Queries]] — examples below. Here are the currently built-in tags: ## page -$page Every page in your space is available via the `page` tag. You can attach _additional_ tags to a page, by either specifying them in the `tags` attribute [[Frontmatter]], or by putting additional [[Tags]] in a stand alone paragraph with no other (textual) content in them, e.g.: #example-tag #another-tag @@ -40,7 +40,8 @@ example-tag ``` ## task -$task + +task Every task in your space is tagged with the `task` tag by default. You tag it with additional tags by using [[Tags]] in the task name, e.g. * [ ] My task #upnext @@ -72,7 +73,6 @@ taskstate where page = "{{@page.name}}" ``` ## template -$template Indexes all pages tagged with `#template`. See [[Templates]] for more information on templates. ```query @@ -81,7 +81,6 @@ template select name limit 5 ## item -$item List items (both bullet point and numbered items) are indexed with the `item` tag, and additional tags can be added using [[Tags]]. Here is an example of a #quote item using a custom [[Attributes|attribute]]: @@ -95,7 +94,6 @@ quote where page = "{{@page.name}}" and tag = "item" select name, by ``` ## paragraph -$paragraph Top-level paragraphs (that is: paragraphs not embedded in a list) are indexed using the `paragraph` tag, any additional tags can be added using [[Tags]]. A paragraph with a #paragraph-tag. @@ -105,7 +103,6 @@ paragraph-tag ``` ## data -$data You can also embed arbitrary YAML data blocks in pages via fenced code blocks and use a tag as a coding language, e.g. ```#person @@ -120,7 +117,6 @@ person ``` ## link -$link All page _links_ are tagged with `link`. You cannot attach additional tags to links. The main two attributes of a link are: * `toPage` the page the link is linking _to_ @@ -137,9 +133,7 @@ link where page = "{{@page.name}}" ``` ## anchor -$anchor - -[[Anchors]] use the `$myanchor` notation to allow deeplinking into a page and are also indexed and queryable. It is not possible to attach additional tags to an anchor. +[[Anchors]] use the $myanchor notation to allow deeplinking into a page and are also indexed and queryable. It is not possible to attach additional tags to an anchor. Here is an example query: @@ -147,8 +141,15 @@ Here is an example query: anchor where page = "{{@page.name}}" ``` +## header +Headers (lines starting with `#`, `##` etc.) are indexed as well and queriable. + +```query +header where page = "{{@page.name}}" limit 3 +``` + + ## tag -$tag The ultimate meta tag is _tag_ itself, which indexes for all tags used, in which page they appear and what their “parent tag” is (the context of the tag: either `page`, `item` or `task`). Here are the tags used/defined in this page: @@ -158,7 +159,6 @@ tag where page = "{{@page.name}}" select name, parent ``` ## attribute -$attribute This is another meta tag, which is used to index all [[Attributes]] used in your space. This is used by e.g. attribute completion in various contexts. You likely don’t need to use this tag directly, but it’s there. ```query diff --git a/website/Tags.md b/website/Tags.md index 3866be9..d45ae3c 100644 --- a/website/Tags.md +++ b/website/Tags.md @@ -1,4 +1,4 @@ Tags in SilverBullet are used to encode types of [[Objects]]. -See [[Objects$tags]] for more information. +See [[Objects#Tags]] for more information.