silverbullet/website/Objects.md

#level/intermediate

SilverBullet automatically builds and maintains an index of objects extracted from all markdown pages in your space. It subsequently allows you to Live Queries this database in (potentially) useful ways.

By design, the truth remains in the markdown: all data indexed as objects will have a representation in markdown text as well. This index can be flushed at any time and be rebuilt from its source markdown files kept in your space (and you can do so on demand if you like using the {[Space: Reindex]} command).

Object representation

Every object has a set of Attributes, some predefined, but you can add any additional custom attributes that you like.

The following attributes are predefined, and you can expect all objects to have them:

• ref: a globally unique identifier, often represented as a pointer to the place (page, position) in your space where the object is defined. For instance, a page object will use the page name as its ref attribute, and a task will use page@pos (where pos is the location the task appears in page).
• tag: the main type, or “tag” of the page, usually a built-in type of the object (see below).

In addition, many objects will also contain:

• tags: an optional set of additional, explicitly assigned tags.
• itags: a set of implicit or inherited tags: including the object’s tag, tags as well as any tags assigned to its containing page. This is useful to answer queries like, “give me all tasks on pages where that page is tagged with person“, which would be expressed as task where itags = "person" (although technically that would also match any tags that have the #person explicitly assigned).

In addition, an object’s attribute set can be dynamically extended using Object Decorators.

Beside these, any number of additional tag-specific and custom Attributes can be defined (see below).

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.

Styling

You can add custom styles to a tag by leveraging the data-tag-name attribute, CSS Attribute Selectors and custom Speace Style's. Every tag gets an attribute added to it called data-tag-name that is set to the tag name with the # symbol stripped out. So given the tag #my-cool-tag the data-tag-name attribute would look like: data-tag-name="my-cool-tag". This allows us to do things like change the color of the #my-cool-tag to have a purple background, limegreen text and bold font by adding the following Space Style:

.sb-hashtag[data-tag-name="my-cool-tag"] {
  background: purple;
  color: limegreen;
  font-weight: bolder;
}

Additionally tags written using angle brackets, such as... # ...can be styled via Space Style like this:

.sb-hashtag[data-tag-name="my cool tag"] {
  background: purple;
  color: limegreen;
  font-weight: bolder;
}

Built-in tags

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, for instance check the very first line of this page that says #level/intermediate.

In addition to ref and tags, the page tag defines a bunch of additional attributes as can be seen in this example query:

page where name = @page.name

Note that you can also query this page using the level/intermediate directly:

level/intermediate

aspiring-page

Aspiring Pages are pages that are linked to, but not yet created.

aspiring-page

table

Markdown table rows are indexed using the table tag, any additional tags can be added using Tags in any of its cells.

Title	Description Text
This is some key	The value contains a #table-tag
Some Row	This is an example row in between two others
Another key	This time without a tag

table

Table headers will be normalized by converting them to lowercase and replacing all non alphanumeric characters with _.

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:

• “If you don’t know where you’re going you may not get there.” [by: Yogi Berra] #quote

And then queried via the #quote tag:

quote where page = @page.name and tag = "item" select name, by

When items are nested, they will contain a parent attrite with a reference to their parent. In addition, itags will also inherit their ancestors’ tags. For instance:

• Root item #root-tag
  • Sub item #sub-tag
    • Leaf item

The Leaf item will be indexed as follows:

item where page = @page.name and name = "Leaf item" select name, parent, itags

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

And can then be queried via either task or upnext.

The following query shows all attributes available for tasks:

upnext

Although you may want to render it using a template such as Library/Core/Query/Task instead:

upnext render [[Library/Core/Query/Task]]

Similar to #item, task objects have a parent attribute when nested (pointing to their parent item), and inherit their ancestor’s tags in itags.

taskstate

Plugs/Tasks support the default x and states (done and not done), but custom states as well. Custom states used across your space are kept in taskstate:

• [NOT STARTED] Task 1
• [IN PROGRESS] Task 2

And can be queried as follows:

taskstate where page = @page.name

template

Indexes all pages tagged with #template. See Templates for more information on templates.

template select name limit 5

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.

paragraph-tag

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.

name: Pete
age: 55

Which then becomes queriable via the person tag:

person 

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
• page the page the link appears on

In addition, the snippet attribute attempts to capture a little bit of context on where the link appears.

Note: this is the data source used for the {[Mentions: Toggle]} feature as well page {[Page: Rename]}.

Here is a query that shows some links that appear in this particular page:

link where page = @page.name limit 5

anchor

Markdown/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:

anchor where page = @page.name

header

Headers (lines starting with #, ## etc.) are indexed as well and queriable.

header where page = @page.name limit 3

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:

tag where page = @page.name select name, parent

space-config

This stores all configuration picked up as part of Space Config

space-config select key

System tags

The following tags are technically implemented a bit differently than the rest, but they are still available to be queried.

command

Enables querying of all Commands available in SilverBullet as well as their assigned keyboard shortcuts.

command order by name limit 5

syscall

Enables querying of all PlugOS syscalls enabled in your space. Mostly useful in the context of Plugs and Space Script development.

syscall limit 5