Quartz's default bases page plugin.
  • TypeScript 97.7%
  • SCSS 2.3%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-11-10 00:13:27 +01:00
.changeset chore: version package 2026-11-09 23:11:57 +00:00
.github/workflows ci: run ci.yml on the changesets version PR and report it as a commit status 2026-11-09 03:47:27 +01:00
src fix: a list holding a file's plain path contains that file (refs.contains(this)) 2026-11-09 05:48:46 +01:00
test test: #31's regression tests expect Obsidian 1.15's behaviour (asLink shows path.md, a base without views lists every file, root folder /) 2026-11-09 05:48:46 +01:00
types chore: centralize type declarations and standardize tooling config 2026-03-16 18:55:26 +01:00
.eslintrc.json chore: centralize type declarations and standardize tooling config 2026-03-16 18:55:26 +01:00
.gitignore chore: migrate to npm publishing 2026-07-23 09:06:44 +02:00
.prettierignore chore: centralize type declarations and standardize tooling config 2026-03-16 18:55:26 +01:00
.prettierrc Initial commit 2026-02-22 10:44:00 +01:00
CHANGELOG.md chore: version package 2026-11-09 23:11:57 +00:00
LICENSE Initial commit 2026-02-22 10:44:00 +01:00
package-lock.json chore: version package 2026-11-09 23:11:57 +00:00
package.json chore: version package 2026-11-09 23:11:57 +00:00
README.md docs(readme): Quartz 5.1 — npm install and config, correct options and defaults 2026-11-09 22:56:17 +01:00
tsconfig.build.json fix: use separate tsconfig for DTS build to avoid vitest dependency 2026-03-22 13:12:01 +01:00
tsconfig.json Initial commit 2026-02-22 10:44:00 +01:00
tsup.config.ts comment cleanup 2026-11-09 05:02:26 +01:00
vitest.config.ts feat: durations as in Obsidian (#15); date() reads date-only strings as local time 2026-11-09 04:52:15 +01:00

@quartz-community/bases-page

A page type and component plugin for Quartz v5 that renders Obsidian Bases (.base files) as database-like filtered views: tables, lists, cards, galleries and boards. Bases can also be embedded in notes (![[Tasks.base]], one view with ![[Tasks.base#Open tasks]]) or written inline as ```base code blocks.

Installation

npx quartz plugin add @quartz-community/bases-page

It is already included (and enabled) in the default quartz.config.yaml.

Usage

Enable the plugin in your Quartz configuration:

plugins:
  - source: "@quartz-community/bases-page"
    enabled: true
    options:
      linkResolution: shortest
    order: 50

Obsidian compatibility

bases-page 1.2 (shipped with Quartz 5.1) evaluates bases like Obsidian. Notable behaviour, some of it changed from earlier versions:

  • A base opens on its first view (defaultViewType has no default).
  • file.name is the name without the extension for Markdown notes (Note) and with it for other files (Plan.canvas, Tasks.base). file.basename never has the extension, file.fullname always does (Note.md).
  • file.tags lists tags as written, with # and their original case, inline tags first. The tags property holds only the frontmatter tags.
  • file.hasTag("a/b"), file.tags.contains("a/b"), containsAny and containsAll also match nested tags (a/b/c) by whole segments, ignoring case and a leading #. file.hasTag("x", "y") is true when the note has any of the tags.
  • Dates are shown as Obsidian shows them (moment's L / L LT) in the site's configuration.locale; .format() and .relative() are locale-aware. date() only reads ISO-style strings (2024-03-05, 2024-03-05 14:30, 2024-03-05T14:30:00Z) and 20240305, in local time; other strings give an empty value.
  • Subtracting dates gives a duration, shown humanized (9 days). duration() takes one whole number and one unit (1d, 2 weeks).
  • imageAspectRatio on cards is height / width (0.5 is a wide cover, 2 a tall one; default 1).
  • file.folder of a file at the root of the vault is /.
  • contains(), containsAny() and containsAll() on text ignore case; on lists they are case-sensitive.
  • this: in a base embedded in a note, this.<key> and this.file are that note's properties and file; on the .base page itself, this is the .base file.
  • Tags link to their tag pages (when tag-page is enabled); links to missing notes get Quartz's broken class.
  • A formula error (such as an unknown function) is shown in its cell.
  • With Quartz 5.1, .base pages follow the site's publish filters (e.g. explicit-publish, drafts): a .base file has no frontmatter, so with explicit-publish it is published only when a published note links to it.

Map views from Obsidian are not supported: a view with an unknown type shows Unknown view type: <type>.

Interaction with unlisted pages

bases-page respects the file.data.unlisted convention. Pages marked unlisted: true (by @quartz-community/unlisted-pages, or by @quartz-community/encrypted-pages via unlistWhenEncrypted: true or per-page unlisted: true / stealth: true) are excluded from every rendered base view — table, list, board, cards, gallery, and any custom view registered via viewRegistry. Both the main entry loop and the internal fileLookup used by .asFile() method resolution skip unlisted pages, so they cannot be dereferenced from formulas on visible pages either.

Note

Base views are server-side rendered HTML baked at build time. They do not update client-side after a visitor successfully decrypts an encrypted page. Graph, explorer, and search all re-hydrate from the patched in-memory content index after decryption and show newly-unlocked pages for the rest of the browser session — base views do not, because they were materialized at build time with unlisted pages already excluded. A visitor who decrypts a revealable encrypted page will see it appear in graph, explorer, and search, but not in any base view on the site, until the site is rebuilt with that page listed. This is the same structural limitation that applies to backlinks, recent notes, folder listings, and tag listings.

TypeScript Override

For advanced use cases (e.g. custom view renderers), you can override in TypeScript:

import * as ExternalPlugin from "./.quartz/plugins";

ExternalPlugin.BasesPage({
  linkResolution: "shortest",
  customViews: {
    myView: ({
      entries,
      view,
      basesData,
      total,
      locale,
      slug,
      allSlugs,
      linkResolution,
      options,
      tagPages,
    }) => {
      // return JSX
    },
  },
});

Built-in Views

  • Table: Sortable columns with automatic type rendering for strings, numbers, booleans, arrays, and links. Supports custom column widths and row heights.
  • List: A compact list view displaying metadata chips for each entry.
  • Cards: A card-based layout with support for an optional image property and configurable card size or aspect ratio.
  • Gallery: An image-focused grid layout designed for visual content with configurable card sizes.
  • Board: A Kanban-style board that groups entries by a specific property (using boardProperty or groupBy), creating columns for each group value.

Features

  • Multiple views per .base file (switchable tabs)
  • Recursive filter trees (and/or/not)
  • Formulas (computed properties via expression engine)
  • Summaries (column aggregations: Count, Average, Min, Max, Sum, Range, Median, Stddev, Earliest, Latest, Checked, Unchecked, Empty, Filled, Unique)
  • Property display configuration
  • Wikilink and Markdown link rendering
  • Sort and grouping

Expression Engine

The expression engine follows a pipeline of source, lexer, Pratt parser, AST, bytecode compiler, and stack interpreter.

Supported Types

  • Strings
  • Numbers
  • Booleans
  • Null
  • Lists
  • Objects
  • Dates
  • Durations
  • Files
  • Links

Operators

  • Arithmetic: +, -, *, /, %
  • Date arithmetic: date ± duration gives a date, date − date gives a duration
  • Comparison: ==, !=, >, <, >=, <=
  • Logical: and / &&, or / ||, not / !

Property Access

  • note.property (or just property): Access a property on the current note.
  • file.name: The name of the file, as in Obsidian: without the extension for Markdown notes (Note), with it for other files (Plan.canvas).
  • file.basename: The name without the extension.
  • file.fullname: The name with the extension (Note.md).
  • file.path: The full path of the file.
  • file.folder: The folder containing the file.
  • file.ext: The file extension.
  • file.tags: A list of tags associated with the file.
  • file.links: A list of links in the file.
  • file.embeds: A list of embeds in the file.
  • file.properties: The note's properties.
  • file.ctime / file.created: The creation date of the file.
  • file.mtime / file.modified: The last modification date of the file.
  • formula.name: Access the result of another formula.
  • this: The note the base is embedded in (this.<key>, this.file, this.note), or the .base file on its own page.

Built-in Global Functions

  • if(condition, then, else)
  • contains(container, item)
  • date(string)
  • duration(string)
  • now()
  • today()
  • number(value)
  • min(a, b, ...)
  • max(a, b, ...)
  • list(value)
  • link(path, display?)
  • image(url)
  • icon(name)
  • html(string)
  • escapeHTML(string)
  • file(path)

Method Functions

Strings

  • contains(substring)
  • startsWith(prefix)
  • endsWith(suffix)
  • lower()
  • upper()
  • trim()
  • replace(pattern, replacement)
  • slice(start, end?)
  • isEmpty()
  • repeat(count)
  • reverse()
  • containsAll(...values)
  • containsAny(...values)
  • split(separator)
  • title()
  • asFile()

Numbers

  • toFixed(digits)
  • round()
  • floor()
  • ceil()
  • abs()
  • isEmpty()

Dates

  • format(formatString)
  • year()
  • month()
  • day()
  • date()
  • time()
  • relative()
  • isEmpty()
  • Fields: .year, .month, .day, .hour, .minute, .second

Durations

  • Fields: .days, .hours, .minutes, .seconds, .milliseconds, .weeks (fractional), .months, .years
  • isEmpty()

Lists

  • sum()
  • mean()
  • count()
  • min()
  • max()
  • round()
  • contains(value)
  • containsAll(...values)
  • containsAny(...values)
  • flat()
  • isEmpty()
  • join(separator)
  • reverse()
  • slice(start, end?)
  • sort()
  • unique()
  • filter(expr), map(expr), flatMap(expr), find(expr), some(expr), every(expr) (value is the current element)
  • .length

File

  • hasTag(...tags)
  • hasLink(link)
  • inFolder(folder)
  • hasProperty(property)
  • asLink(display?)

Objects

  • isEmpty()
  • keys()
  • values()

Extending with Custom Views

Community extensions can register custom view types using the view registry.

Registering a View

import { viewRegistry } from "@quartz-community/bases-page/registry";

viewRegistry.register({
  id: "my-custom-view",
  name: "My Custom View",
  icon: "star",
  render: (props) => {
    const { entries, view, basesData, total, locale, slug, allSlugs, linkResolution, options } =
      props;
    // Return your React/Preact component
  },
  css: `.my-custom-view { color: red; }`,
  afterDOMLoaded: `console.log("My custom view loaded");`,
  options: { enableFeatureX: true },
});

Interfaces

ViewTypeRegistration

interface ViewTypeRegistration {
  id: string;
  name: string;
  icon?: string;
  render: ViewRenderer;
  css?: string;
  afterDOMLoaded?: string;
  options?: Record<string, unknown>;
}

ViewRendererProps

interface ViewRendererProps {
  entries: BasesEntry[];
  view: BasesView;
  basesData: BasesData;
  total: number;
  locale: string;
  slug: string;
  allSlugs: string[];
  linkResolution: "absolute" | "relative" | "shortest";
  options?: Record<string, unknown>;
  tagPages?: boolean; // whether tags link to tag pages
}

Passing Options to a Custom View

Community plugins can use the options field to accept configuration at registration time. This is useful for feature flags, API keys, or other plugin-level settings.

import { viewRegistry } from "@quartz-community/bases-page/registry";
import type { LeafletMapPluginOptions } from "./types";

const defaultOptions: LeafletMapPluginOptions = {
  enableCopyTool: false,
};

export function registerLeafletMap(userOpts?: Partial<LeafletMapPluginOptions>): void {
  const opts = { ...defaultOptions, ...userOpts };
  viewRegistry.register({
    ...leafletMapViewRegistration,
    options: opts,
  });
}

In the renderer, these options are available via props.options and should be cast to the plugin's options type.

Compiler API

The expression engine is available as a public API for advanced usage. Import from @quartz-community/bases-page/compiler.

import {
  compile,
  evaluate,
  evaluateFilter,
  resolvePropertyValue,
} from "@quartz-community/bases-page/compiler";

// Compile an expression to bytecode
const compiled = compile("note.price * 1.2");

// Evaluate an expression in a context
const result = evaluate("note.price * 1.2", context);

// Evaluate a filter node
const isMatch = evaluateFilter(filterNode, context);

// Resolve a property path
const value = resolvePropertyValue("file.name", context);

EvalContext Shape

interface EvalContext {
  note: Record<string, unknown>;
  file: {
    name: string;
    basename: string;
    fullname?: string;
    path: string;
    folder: string;
    ext: string;
    tags: string[];
    links: string[];
    embeds?: string[];
    properties?: Record<string, unknown>;
    created?: string | Date;
    modified?: string | Date;
    ctime?: Date;
    mtime?: Date;
    size?: number;
  };
  formula: Record<string, unknown>;
  /** `this`: the embedding note (or the .base file): `this.file`, `this.note`, `this.<key>` */
  self?: {
    file: Partial<EvalContext["file"]>;
    note?: Record<string, unknown>;
    [key: string]: unknown;
  };
  /** The site's locale, for date and duration display */
  locale?: string;
}

Package Exports

  • .: Main plugin entry (BasesPage, BasesBody, viewRegistry, registerCustomViews, compiler API, types)
  • ./types: All type definitions
  • ./components: React/Preact components (BasesBody, ViewSelector)
  • ./registry: View registry singleton and registerCustomViews helper
  • ./compiler: Expression engine (compile, evaluate, evaluateFilter, resolvePropertyValue)

Configuration Options

Option Type Default Description
defaultViewType string unset Open bases on their first view of this type. Unset, a base opens on its first view, as in Obsidian.
linkResolution "absolute" | "relative" | "shortest" "shortest" How to resolve internal links in view renderers. Should match configuration.links.markdownLinkResolution.
customViews Record<string, ViewRenderer> {} Custom view renderers (keyed by view type; override or add view types). Requires a quartz.ts override.

License

MIT