as-notes

Category: Docs & Knowledge | Uploader: appsoftwareltd | Downloads: 0 | Version: v1.0（Latest）
Use when working with the AS Notes VS Code extension — a Personal Knowledge Management System (PKMS). Two use cases: (1) writing/contributing notes in AS Notes format (wikilinks, task tags, aliases, journal entries, kanban cards, outliner mode) — notes can also be published as a static HTML site, and (2) helping users use, configure, and troubleshoot AS Notes (settings, commands, keyboard shortcuts, workspace setup, backlinks, encryption).
Changelog: Source: GitHub https://github.com/appsoftwareltd/as-notes
Directory Structure

Current level: tools/skills/as-notes-agent-use/
📄 SKILL.md 12.7 KB
SKILL.md

---
name: as-notes
description: Use when working with the AS Notes VS Code extension — a Personal Knowledge Management System (PKMS). Two use cases: (1) writing/contributing notes in AS Notes format (wikilinks, task tags, aliases, journal entries, kanban cards, outliner mode) — notes can also be published as a static HTML site, and (2) helping users use, configure, and troubleshoot AS Notes (settings, commands, keyboard shortcuts, workspace setup, backlinks, encryption).
license: MIT
metadata:
  author: appsoftwareltd
  version: "1.3"
---

# AS Notes — VS Code Extension

AS Notes turns VS Code into a PKMS. Activates when `.asnotes/` exists at the workspace root.

- VS Code Marketplace: `appsoftwareltd.as-notes`
- Docs: https://docs.asnotes.appsoftware.com
- Demo: https://github.com/appsoftwareltd/as-notes-demo-notes

---

## How to Use This Skill

**Use case 1 — Writing notes:** Create/edit markdown using wikilinks, task tags, aliases, journal entries, kanban cards, outliner bullets. Notes authored in AS Notes format can be published as a static HTML site (docs, content) via the `html-conversion` tool. → [Writing Notes in AS Notes Format](#writing-notes-in-as-notes-format), [Publishing to Static HTML](#publishing-to-static-html)

**Use case 2 — Help & troubleshooting:** Answer questions about features, settings, commands, keyboard shortcuts, workspace setup, and diagnose problems. → Reference sections below.

---

## Writing Notes in AS Notes Format

### Standard page

```markdown
---
aliases:
  - Short Name
  - Another Name
---

# Page Title

Link to [[Page Name]] or [[Subfolder/Topic]].
Nested wikilinks: [[Specific [[Topic]] Details]].
```

- YAML front matter optional; include only when aliases are needed
- First `# heading` is the page title in the index
- Omit `.md` in wikilinks — `[[My Page]]` resolves to `My Page.md`

### Task lines

```markdown
- [ ] Plain task
- [ ] #P1 Critical
- [ ] #P2 #W Waiting on approval #D-2026-03-20
- [ ] #P3 Low priority #C-2026-03-15
- [x] Completed task
```

- Tags appear anywhere; stripped from display text
- Only first priority tag (`#P1`–`#P9`) is used
- `#W` toggles; dates must be `YYYY-MM-DD`

### Daily journal entry

File: `journals/2026_03_15.md` (folder configurable via `as-notes.journalFolder`)

```markdown
# 2026-03-15

## Tasks
- [ ] Morning standup
- [ ] Review [[Project Alpha]] PR

## Notes
Discussed [[Team Meeting]] outcomes with [[Alice]].
```

### Outliner-mode page

Every line begins with `- `. Structure with indentation:

```markdown
- # Page Title
- Top level idea about [[Topic]]
  - Supporting detail
    - Nested detail
- [ ] #P2 Task #D-2026-03-20
  - [ ] Sub-task
```

### Kanban card file

Save as `card_YYYYMMDD_HHmmssfff_<id>_<slug>.md` inside `kanban/<board-slug>/`:

```markdown
---
title: Card title
lane: todo
priority: medium
assignee: 
labels: []
dueDate: ""
created: "2026-03-15T10:00:00.000Z"
updated: "2026-03-15T10:00:00.000Z"
---
Card description in Markdown.

## entry 2026-03-15T10:00:00.000Z
Timestamped comment.
```

---

## Workspace Initialisation

Requires `.asnotes/` at workspace root. Without it: passive mode (no index, commands prompt to initialise).

**Initialise:** Command Palette → **AS Notes: Initialise Workspace**

- **AS Notes: Rebuild Index** — drop and recreate the index
- **AS Notes: Clean Workspace** — remove `.asnotes/`, reset to passive mode (preserves `.asnotesignore`)

### .asnotesignore

Gitignore-syntax file at workspace root. Watched; re-scans on change. Default:

```
logseq/
.obsidian/
.trash/
```

- No `/` prefix → matches at any depth; `/` prefix → anchored to workspace root
- VS Code `files.exclude` / `search.exclude` settings are also respected

---

## Supported File Types

`.md` and `.markdown`

---

## Wikilinks

```markdown
[[Page Name]]
[[Subfolder/Page Name]]
[[Outer [[Inner]] text]]    ← nested; each balanced pair is a valid link
```

**Resolution order:** direct filename match → alias match → auto-create in source directory

**Disambiguation** (multiple files with same name): same directory wins, otherwise closest folder by distance.

**Aliases** — YAML front matter: `aliases: [Short Name, Another Name]`
`[[Short Name]]` navigates to the page declaring that alias. Hover shows `Short Name.md → ActualPage.md`. Backlink counts include alias refs.

**Rename sync** — editing wikilink text and moving the cursor away offers to rename the `.md` file and update all matching links.

**Autocomplete** — type `[[` to list all pages/aliases; selecting appends `]]`.

**Colour** — `as-notes.wikilinkColour` (hex, e.g. `#3794ff`); empty = theme default.

---

## Task / TODO Management

**Toggle:** `Ctrl+Shift+Enter` / `Cmd+Shift+Enter` — cycles `plain → - [ ] → - [x] → plain` on the current line. Multi-cursor supported.

### Metadata tags

| Tag | Description |
|---|---|
| `#P1` / `#P2` / `#P3` | Priority — Critical / High / Normal |
| `#W` | Waiting |
| `#D-YYYY-MM-DD` | Due date |
| `#C-YYYY-MM-DD` | Completion date |

Tags stripped from display. First priority tag wins. Dates: `YYYY-MM-DD`.

### Tasks sidebar — `Ctrl+Alt+T` / `Cmd+Alt+T`

**Group By:** Page · Priority (P1→P2→P3→None, sorted by due date) · Due Date (Overdue/Today/This Week/Later/None) · Completion Date

**Filters:** TODO ONLY (default on) · WAITING ONLY · Filter by page (case-insensitive)

---

## Backlinks Panel — `Ctrl+Alt+B` / `Cmd+Alt+B`

All incoming wikilink references to the current file, displayed as context chains.

- **Flat by page** (default) — sorted by source page name
- **Grouped by chain** — grouped by link chain pattern (e.g. `[[Project]] → [[Tasks]] → [[Topic]]`)
- Default mode: `as-notes.backlinkGroupByChain` (default `false`)
- Context verbosity: compact or wrapped — `as-notes.backlinkWrapContext` (default `false`)
- Right-click any wikilink → **View Backlinks** for that page (works with aliases and forward refs)

---

## Daily Journal — `Ctrl+Alt+J` / `Cmd+Alt+J`

Creates or opens today's file. Filename: `YYYY_MM_DD.md` in `journals/` (or `as-notes.journalFolder`). Template: `journal_template.md` — `YYYY-MM-DD` replaced on creation. Folder and template auto-created on first use.

---

## Slash Commands

Type `/` in any markdown file. Filter by typing. Suppressed in code blocks, inline code, and YAML front matter.

### General

| Command | Action |
|---|---|
| **Today** | Insert `[[YYYY_MM_DD]]` wikilink |
| **Date Picker** | Date input → insert as wikilink |
| **Code (inline)** | Insert `` ` ` `` with cursor inside |
| **Code (multiline)** | Insert fenced code block |
| **Table** | Prompt for cols/rows, insert table |
| **Table: Add Column(s)** | Add cols after cursor |
| **Table: Add Row(s)** | Add rows after cursor |
| **Table: Format** | Normalise column widths |
| **Table: Remove Row (Current)** | Remove row at cursor |
| **Table: Remove Column (Current)** | Remove column at cursor |
| **Table: Remove Row(s) Above/Below** | Prompt for count, remove |
| **Table: Remove Column(s) Right/Left** | Prompt for count, remove |

Table commands shown as **(Pro)** for free users.

### Task commands *(on a task line only)*

| Command | Action |
|---|---|
| **Task: Priority 1/2/3** | Insert/replace priority tag |
| **Task: Waiting** | Toggle `#W` |
| **Task: Due Date** | Date input → insert/replace `#D-YYYY-MM-DD` |
| **Task: Completion Date** | Date input → insert/replace `#C-YYYY-MM-DD` |

---

## Outliner Mode

Enable: `as-notes.outlinerMode` or **AS Notes: Toggle Outliner Mode**. Every line begins with `- `.

| Key | Action |
|---|---|
| **Enter** | New bullet at same indent (todo lines continue as `- [ ]`) |
| **Tab** | Indent one level (max: one deeper than line above) |
| **Shift+Tab** | Outdent one level |
| **Ctrl+Shift+Enter** | Cycle bullet → `- [ ]` → `- [x]` → bullet |
| **Ctrl+V / Cmd+V** | Each clipboard line → separate bullet |

**Code block completion** (all markdown files): type `` ``` `` + optional language + Enter → closing `` ``` `` inserted with cursor inside.

---

## File Drag & Drop / Paste

Drop files or paste images onto a markdown editor. Saved to `<workspace>/<as-notes.assetPath>/<filename>` (default: `assets/images`).

---

## Kanban Board *(Pro)*

```
kanban/<board-slug>/
  board.yaml
  card_YYYYMMDD_HHmmssfff_<id>_<slug>.md
  assets/<card-id>/<filename>
```

See [Kanban card file](#kanban-card-file) above for card format. Priority levels: `critical` · `high` · `medium` · `low` · `none`

Default lanes: **TODO**, **DOING**, **DONE** (TODO and DONE protected). Add/rename/reorder/remove additional lanes in the editor panel. Attach files to cards via drag & drop; size warning: `as-notes.kanbanAssetSizeWarningMB` (default 10 MB).

| Command | Description |
|---|---|
| **AS Notes: Open Kanban Board** | Open editor panel |
| **AS Notes: New Kanban Card** | Create card |
| **AS Notes: Select Kanban Board** | Pick board from list |
| **AS Notes: Create Kanban Board** | New board |
| **AS Notes: Rename Kanban Board** | Rename current board |
| **AS Notes: Delete Kanban Board** | Delete board and all data |

---

## Encrypted Notes *(Pro)*

`.enc.md` files are encrypted at rest, excluded from the search index, never read as plain text.

- **Algorithm:** AES-256-GCM, random 12-byte nonce per encryption
- **Key derivation:** PBKDF2-SHA256, 100,000 iterations
- **Storage:** passphrase in OS keychain (VS Code SecretStorage) — never written to disk
- **File marker:** `ASNOTES_ENC_V1:<base64url payload>` — detected by Git pre-commit hook

| Command | Description |
|---|---|
| **AS Notes: Set Encryption Key** | Save passphrase to keychain |
| **AS Notes: Clear Encryption Key** | Remove passphrase |
| **AS Notes: Create Encrypted Note** | New `.enc.md` file |
| **AS Notes: Create Encrypted Journal Note** | Today's journal as `.enc.md` |
| **AS Notes: Encrypt / Decrypt All Notes** | Encrypt or decrypt all `.enc.md` files |
| **AS Notes: Encrypt / Decrypt Current Note** | Encrypt or decrypt active file |

---

## Pro Licence

Setting: `as-notes.licenceKey` (machine-scoped, not synced). Status bar shows **AS Notes (Pro)** when active. Contact: https://www.appsoftware.com/contact

---

## Settings

| Setting | Default | Description |
|---|---|---|
| `as-notes.periodicScanInterval` | `300` | Background scan interval (seconds). `0` disables. Min: `30`. |
| `as-notes.journalFolder` | `journals` | Journal folder, relative to workspace root. |
| `as-notes.licenceKey` | *(empty)* | Pro licence key. Machine-scoped. |
| `as-notes.assetPath` | `assets/images` | Folder for dropped/pasted files. |
| `as-notes.enableLogging` | `false` | Diagnostic logging to `.asnotes/logs/`. Requires reload. Also: `AS_NOTES_DEBUG=1`. |
| `as-notes.wikilinkColour` | *(empty)* | Hex wikilink colour (e.g. `#3794ff`). Empty = theme default. |
| `as-notes.backlinkGroupByChain` | `false` | Backlinks: group by chain (`true`) or flat by page (`false`). |
| `as-notes.backlinkWrapContext` | `false` | Backlinks: wrap context (`true`) or compact (`false`). |
| `as-notes.outlinerMode` | `false` | Outliner Mode. Window-scoped. |
| `as-notes.kanbanAssetSizeWarningMB` | `10` | Kanban attachment size warning (MB). `0` disables. |

---

## Keyboard Shortcuts

| Action | Windows/Linux | macOS |
|---|---|---|
| Toggle todo | `Ctrl+Shift+Enter` | `Cmd+Shift+Enter` |
| Backlinks panel | `Ctrl+Alt+B` | `Cmd+Alt+B` |
| Daily journal | `Ctrl+Alt+J` | `Cmd+Alt+J` |
| Tasks panel | `Ctrl+Alt+T` | `Cmd+Alt+T` |

---

## Publishing to Static HTML

`html-conversion` is a Node.js tool (`html-conversion/` in the repo) that converts a notes workspace to a static HTML site.

- Scans `--input` for `.md` → outputs `.html` files
- `[[wikilinks]]` → relative `.html` links; auto-generates `<nav>` sidebar
- Creates placeholder pages for missing wikilink targets
- Content in `<article class="markdown-body">` — compatible with `github-markdown-css`
- **Wipes output directory before each run**

```bash
cd html-conversion && npm install && npm run build
npm run convert -- --input <notes-dir> --output <output-dir>
```

| Flag | Description |
|---|---|
| `--input <dir>` | Source `.md` directory |
| `--output <dir>` | Output directory (wiped each run) |
| `--stylesheet <url>` | Inject `<link rel="stylesheet">`. Repeatable; CDN URLs or relative paths. |
| `--asset <file>` | Copy local file to output. Repeatable. |

```bash
npm run convert -- \
  --input ../docs-src/pages --output ../docs \
  --stylesheet https://cdn.jsdelivr.net/npm/github-markdown-css/github-markdown-light.css \
  --stylesheet docs.css --asset ../docs-src/docs.css
```

**GitHub Pages / CI:** commit output to `docs/`; enable GitHub Pages in repo settings.

```yaml
- name: Build docs
  run: |
    cd html-conversion && npm ci && npm run build
    npm run convert -- --input ../docs-src/pages --output ../docs
```

`index.md` → `index.html` (shown as "Home"). Pages listed alphabetically; `index` always first.
Comments 0
Latest | Hot
Please login before commenting.
No comments yet. Be the first one!
as-notes

Directory Structure

SKILL.md

Report

Notice
