diff --git a/README.md b/README.md index 87f002e..b356a96 100644 --- a/README.md +++ b/README.md @@ -17,6 +17,14 @@ This plugin shows the full name helping to identify the backlinks better ![Full path](./images/full-path.png) +## Demo vault + +A demo vault with usage examples ships with every release. You can access it via any of the following: + +1. Running the **Backlink Full Path: Open demo vault** command. +2. Downloading `backlink-full-path.demo-vault.zip` from the [Releases](https://github.com/mnaoumov/obsidian-backlink-full-path/releases). +3. Browsing its source in [`demo-vault/`](./demo-vault/README.md) in this repository. + ## Installation The plugin is available in [the official Community Plugins repository](https://obsidian.md/plugins?id=backlink-full-path). diff --git a/demo-vault/.gitignore b/demo-vault/.gitignore new file mode 100644 index 0000000..da9b885 --- /dev/null +++ b/demo-vault/.gitignore @@ -0,0 +1,13 @@ +# Churny / runtime-generated Obsidian state. +.obsidian/workspace.json +.obsidian/hotkeys.json + +# Built plugins are release-injected by archivePluginDemoVault at release time — +# both the plugin under test AND the obsidian-dev-utils-owned Demo Vault Helper +# bootstrap plugin (which installs, configures, and enables CodeScript Toolkit at +# runtime). Nothing helper-related is committed; commit only the baked settings +# file for the plugin under test. +.obsidian/plugins/* +!.obsidian/plugins/backlink-full-path/ +.obsidian/plugins/backlink-full-path/* +!.obsidian/plugins/backlink-full-path/data.json diff --git a/demo-vault/.markdownlint-cli2.jsonc b/demo-vault/.markdownlint-cli2.jsonc new file mode 100644 index 0000000..bb807df --- /dev/null +++ b/demo-vault/.markdownlint-cli2.jsonc @@ -0,0 +1,12 @@ +{ + // Scoped markdownlint config for the demo vault. The notes are an Obsidian + // vault, so two default rules are inherently incompatible and disabled here; + // every other rule still applies so the notes stay clean. + "config": { + // Notes intentionally open with a `[Docs](...)` link, not a heading. + "MD041": false, + // `[[wikilinks]]` are Obsidian's native link syntax; markdownlint parses + // them as undefined shortcut reference links. + "MD052": false + } +} diff --git a/demo-vault/.obsidian/app.json b/demo-vault/.obsidian/app.json new file mode 100644 index 0000000..e13f1f9 --- /dev/null +++ b/demo-vault/.obsidian/app.json @@ -0,0 +1,8 @@ +{ + "attachmentFolderPath": "_assets/attachments", + "newLinkFormat": "shortest", + "useMarkdownLinks": false, + "showUnsupportedFiles": true, + "defaultViewMode": "source", + "livePreview": true +} diff --git a/demo-vault/.obsidian/community-plugins.json b/demo-vault/.obsidian/community-plugins.json new file mode 100644 index 0000000..b402c9d --- /dev/null +++ b/demo-vault/.obsidian/community-plugins.json @@ -0,0 +1,4 @@ +[ + "demo-vault-helper", + "backlink-full-path" +] diff --git a/demo-vault/00 Start.md b/demo-vault/00 Start.md new file mode 100644 index 0000000..10d02e6 --- /dev/null +++ b/demo-vault/00 Start.md @@ -0,0 +1,17 @@ +Welcome to the [Backlink Full Path](https://github.com/mnaoumov/obsidian-backlink-full-path/) demo vault. Obsidian's core **Backlinks** pane shows only each linking note's file name - so several notes that share a name (three different `Meeting` notes, say) look identical. **Backlink Full Path** adds each note's folder path to that pane so you can tell them apart, with plenty of options for how the path is shown. + +**How to see it:** open [[Shared topic]], then open the **Backlinks** pane (the link icon in the right sidebar, or the "Backlinks" view). Three notes all named `Meeting` link here - with the plugin enabled, each backlink shows its full folder path. + +> [!TIP] Interactive buttons +> +> The two setup notes have **Run** buttons, powered by [`CodeScript Toolkit`](https://github.com/mnaoumov/obsidian-codescript-toolkit/), which this vault installs for you automatically on first open (see [[CodeScript Toolkit prerequisite]]). The feature itself is just the Backlinks pane, so the feature notes have no buttons. + +## Feature + +- [[Backlink full path]] +- [[Settings]] + +## Setup + +- [[Code buttons check]] +- [[CodeScript Toolkit prerequisite]] diff --git a/demo-vault/Backlink full path.md b/demo-vault/Backlink full path.md new file mode 100644 index 0000000..ee1c2a9 --- /dev/null +++ b/demo-vault/Backlink full path.md @@ -0,0 +1,18 @@ +[Docs](https://github.com/mnaoumov/obsidian-backlink-full-path/) + +# Backlink full path + +Open [[Shared topic]] and look at its **Backlinks** pane. Three different notes link to it, and all three are named `Meeting`: + +- [[Projects/Alpha/Meeting]] +- [[Projects/Beta/Meeting]] +- [[Notes/Meeting]] + +Without this plugin, the Backlinks pane lists three identical `Meeting` entries. With it enabled, each one shows its folder path (`Projects/Alpha`, `Projects/Beta`, `Notes`) so you know which is which. + +## Try it + +1. Open [[Shared topic]]. +2. Open the **Backlinks** pane (right sidebar link icon, or the command **Backlinks: Show backlinks**). +3. Notice each backlink now carries its full path. +4. Head to [[Settings]] and tweak how the path is rendered - depth, highlighting, extension, ordering, and more. diff --git a/demo-vault/Code buttons check.md b/demo-vault/Code buttons check.md new file mode 100644 index 0000000..4ebeb04 --- /dev/null +++ b/demo-vault/Code buttons check.md @@ -0,0 +1,13 @@ +[Docs](https://github.com/mnaoumov/obsidian-codescript-toolkit/) + +# Code buttons check + +If [`CodeScript Toolkit`](https://github.com/mnaoumov/obsidian-codescript-toolkit/) is installed and enabled, the block below renders as a **Run** button. Click it - a notice should appear. If you only see a code block, install the prerequisite first: [[CodeScript Toolkit prerequisite]]. + +```code-button +--- +caption: Click me +--- +import { Notice } from 'obsidian'; +new Notice('Code buttons work - you are ready to explore the demo vault.'); +``` diff --git a/demo-vault/CodeScript Toolkit prerequisite.md b/demo-vault/CodeScript Toolkit prerequisite.md new file mode 100644 index 0000000..bc54df6 --- /dev/null +++ b/demo-vault/CodeScript Toolkit prerequisite.md @@ -0,0 +1,22 @@ +[Docs](https://github.com/mnaoumov/obsidian-codescript-toolkit/) + +# CodeScript Toolkit prerequisite + +The **Run** buttons in this vault are powered by [`CodeScript Toolkit`](https://github.com/mnaoumov/obsidian-codescript-toolkit/). This vault installs and enables it for you automatically the first time you open the vault (and trust it). Nothing here is required to explore Backlink Full Path - it just enhances the core Backlinks pane. + +## If the buttons do not work + +If a code block does not turn into a button, install CodeScript Toolkit manually: + +1. Open **Settings -> Community plugins -> Browse**. +2. Search for **CodeScript Toolkit**, install it, and enable it. +3. Reopen a note that has a **Run** button. + +Or click the button below to install and enable it (needs an internet connection): + +```code-button +--- +caption: Install CodeScript Toolkit +--- +await require('/demoSetup.ts').installAndEnable(app, 'fix-require-modules'); +``` diff --git a/demo-vault/Notes/Meeting.md b/demo-vault/Notes/Meeting.md new file mode 100644 index 0000000..e1d0f54 --- /dev/null +++ b/demo-vault/Notes/Meeting.md @@ -0,0 +1,7 @@ +[Docs](https://github.com/mnaoumov/obsidian-backlink-full-path/) + +# Meeting (general notes) + +A general meeting note. Related to [[Shared topic]]. + +The third note named `Meeting`; the Backlinks pane shows its path as `Notes`. diff --git a/demo-vault/Projects/Alpha/Meeting.md b/demo-vault/Projects/Alpha/Meeting.md new file mode 100644 index 0000000..e61ee99 --- /dev/null +++ b/demo-vault/Projects/Alpha/Meeting.md @@ -0,0 +1,7 @@ +[Docs](https://github.com/mnaoumov/obsidian-backlink-full-path/) + +# Meeting (Project Alpha) + +Notes from the Alpha project meeting. Related to [[Shared topic]]. + +This note is named `Meeting`, like two others in the vault - the Backlinks pane of [[Shared topic]] shows its full path, `Projects/Alpha`, to keep it distinct. diff --git a/demo-vault/Projects/Beta/Meeting.md b/demo-vault/Projects/Beta/Meeting.md new file mode 100644 index 0000000..63126ab --- /dev/null +++ b/demo-vault/Projects/Beta/Meeting.md @@ -0,0 +1,7 @@ +[Docs](https://github.com/mnaoumov/obsidian-backlink-full-path/) + +# Meeting (Project Beta) + +Notes from the Beta project meeting. Related to [[Shared topic]]. + +Also named `Meeting`; in the Backlinks pane of [[Shared topic]] it is shown as `Projects/Beta` so you can tell it apart from the others. diff --git a/demo-vault/README.md b/demo-vault/README.md new file mode 100644 index 0000000..a9c923e --- /dev/null +++ b/demo-vault/README.md @@ -0,0 +1,9 @@ +# Backlink Full Path demo vault + +A small Obsidian vault that demonstrates the [Backlink Full Path](https://github.com/mnaoumov/obsidian-backlink-full-path) plugin - it adds each source note's folder path to the core **Backlinks** pane so notes that share a name are no longer indistinguishable. + +Open [00 Start](<./00 Start.md>), then open [Shared topic](<./Shared topic.md>) and look at its Backlinks pane: three notes all named `Meeting` link to it, each shown with its full path. + +## First open + +The first time you open this vault, Obsidian treats it as **untrusted**, so the bundled plugins are listed but not loaded until you **Trust author and enable plugins** and reload. After that, the Demo Vault Helper installs [CodeScript Toolkit](https://github.com/mnaoumov/obsidian-codescript-toolkit) (which powers the optional **Run** buttons in the setup notes) and opens the start note for you. diff --git a/demo-vault/Settings.md b/demo-vault/Settings.md new file mode 100644 index 0000000..76b1ff8 --- /dev/null +++ b/demo-vault/Settings.md @@ -0,0 +1,20 @@ +[Docs](https://github.com/mnaoumov/obsidian-backlink-full-path/) + +# Settings + +Open **Settings -> Community plugins -> Backlink Full Path** to configure the pane. Each option below lists the setting key stored in the plugin's `data.json`. + +## Which path to show + +- `pathDepth` - how many parent folders to include (0 shows the whole path). +- `rootPaths` - folders to treat as roots; paths under them are shown relative to the root. +- `shouldReversePathParts` - render the path from the file outwards instead of from the root inwards. +- `shouldShowEllipsisForSkippedPathParts` - show an ellipsis where parts were trimmed by `pathDepth` or a root. + +## How it looks + +- `shouldHighlightFileName` - visually emphasize the file name within the full path. +- `shouldIncludeExtension` - keep the `.md` (or other) extension in the shown name. +- `shouldDisplayParentPathOnSeparateLine` - put the folder path on its own line above the file name. + +Change any of these and watch the Backlinks pane of [[Shared topic]] update live. diff --git a/demo-vault/Shared topic.md b/demo-vault/Shared topic.md new file mode 100644 index 0000000..b6c4c41 --- /dev/null +++ b/demo-vault/Shared topic.md @@ -0,0 +1,5 @@ +[Docs](https://github.com/mnaoumov/obsidian-backlink-full-path/) + +# Shared topic + +This is the note whose backlinks the demo inspects. Open the **Backlinks** pane and look at the three `Meeting` notes that link here - each one shows its full folder path thanks to [[Backlink full path]]. diff --git a/demo-vault/_assets/CodeScriptToolkit/demoSetup.ts b/demo-vault/_assets/CodeScriptToolkit/demoSetup.ts new file mode 100644 index 0000000..5dc0c6d --- /dev/null +++ b/demo-vault/_assets/CodeScriptToolkit/demoSetup.ts @@ -0,0 +1,16 @@ +import type { App } from 'obsidian'; + +import { Notice } from 'obsidian'; +import { + enableCommunityPlugin, + installCommunityPlugin +} from 'obsidian-dev-utils/obsidian/community-plugins'; + +// Backlink Full Path changes how the core Backlinks pane renders each source note's path, so there is +// Nothing for a code-button to drive - you just open a note and look at its backlinks. The only helper the +// Vault needs is the shared CodeScript Toolkit installer used by the prerequisite note's button. +export async function installAndEnable(app: App, pluginId: string): Promise { + await installCommunityPlugin({ app, pluginId }); + await enableCommunityPlugin({ app, pluginId }); + new Notice(`Installed and enabled: ${pluginId}`); +} diff --git a/demo-vault/_assets/CodeScriptToolkit/startup.ts b/demo-vault/_assets/CodeScriptToolkit/startup.ts new file mode 100644 index 0000000..dc13a1c --- /dev/null +++ b/demo-vault/_assets/CodeScriptToolkit/startup.ts @@ -0,0 +1,10 @@ +// Per-vault startup script, run by the universal Demo Vault Helper plugin (via CodeScript +// Toolkit's require) once CodeScript Toolkit is installed and enabled. This is where each +// plugin's demo vault does its own startup setup. Here it just opens the landing note. + +const START_NOTE_PATH = '00 Start.md'; + +const startNote = app.vault.getFileByPath(START_NOTE_PATH); +if (startNote) { + void app.workspace.getLeaf(false).openFile(startNote); +} diff --git a/dprint.json b/dprint.json new file mode 100644 index 0000000..6981058 --- /dev/null +++ b/dprint.json @@ -0,0 +1,10 @@ +{ + "extends": "./node_modules/obsidian-dev-utils/dist/templates/dprint.json", + "excludes": [ + "dist", + "**/node_modules", + "**/*-lock.json", + "**/*.md", + "demo-vault" + ] +} diff --git a/src/demo-vault.no-app.integration.test.ts b/src/demo-vault.no-app.integration.test.ts new file mode 100644 index 0000000..5543297 --- /dev/null +++ b/src/demo-vault.no-app.integration.test.ts @@ -0,0 +1,21 @@ +import process from 'node:process'; +import { registerDemoVaultCoverageSuite } from 'obsidian-dev-utils/script-utils/demo-vault-coverage'; +import { getRootFolder } from 'obsidian-dev-utils/script-utils/root'; + +// Keeps the in-repo `demo-vault/` in sync with the plugin's public surface WITHOUT +// Launching Obsidian: it reflects the real config from source and asserts every +// Setting is documented in a note, and that the guard note/member still exist +// (rename drift). Backlink Full Path enhances the core Backlinks pane and exposes +// No public API interface, so only the PluginSettings config class is reflected; +// The plugin's runtime behavior is covered by the other integration tests. +registerDemoVaultCoverageSuite({ + configInterfaces: [{ interfaceName: 'PluginSettings', sourcePath: 'src/plugin-settings.ts' }], + interfaces: [], + nonTrivialGuard: { + expectDemoNote: 'Settings.md', + expectMember: 'pathDepth', + interfaceName: 'PluginSettings', + sourcePath: 'src/plugin-settings.ts' + }, + rootFolder: getRootFolder() ?? process.cwd() +});