Docs #1

Merged
gffranco merged 15 commits from docs into main 2026-05-30 18:35:41 +00:00
4 changed files with 444 additions and 105 deletions
Showing only changes of commit 1753292814 - Show all commits
+2 -3
View File
@@ -71,9 +71,8 @@ nuwiki/
├── development/ # Developer-only tooling and docs (not shipped) ├── development/ # Developer-only tooling and docs (not shipped)
│ ├── ONBOARDING.md # This file │ ├── ONBOARDING.md # This file
│ ├── nuwiki-architecture.html │ ├── nuwiki-architecture.html
│ ├── start-nvim.sh # Launch Neovim against a scratch wiki │ ├── start-nvim.sh # Launch Neovim against a generated sample wiki
│ ├── start-vim.sh # Launch Vim against a scratch wiki │ ├── start-vim.sh # Launch Vim against a generated sample wiki
│ ├── test-personal-wiki.sh # Launch Vim against your real wiki
│ ├── syntax-diag.vim # Dump highlighting state for debugging │ ├── syntax-diag.vim # Dump highlighting state for debugging
│ └── tests/ # Editor keymap/command harnesses (run in CI) │ └── tests/ # Editor keymap/command harnesses (run in CI)
│ ├── test-keymaps.sh # Neovim keymap harness │ ├── test-keymaps.sh # Neovim keymap harness
+215 -31
View File
@@ -55,52 +55,236 @@ ensure_binary() {
log "binary ready: $bin (built $(date -r "$built" '+%Y-%m-%d %H:%M:%S'))" log "binary ready: $bin (built $(date -r "$built" '+%Y-%m-%d %H:%M:%S'))"
} }
seed_wiki() { # write_sample_wiki DIR — lay down a fixture that exercises every vimwiki
mkdir -p "$WIKI_DIR" "$WIKI_DIR/diary" # feature nuwiki supports: one page per feature group plus a diary. Kept
if [[ ! -f "$WIKI_DIR/index.wiki" ]]; then # identical to the copy in start-vim.sh so both launchers showcase the
cat > "$WIKI_DIR/index.wiki" <<'EOF' # same surface. Heredocs use a quoted delimiter so `$math`, backticks,
= Welcome to nuwiki = # and backslashes land verbatim.
write_sample_wiki() {
local root="$1"
mkdir -p "$root" "$root/diary"
This is a scratch wiki created by start-nvim.sh. Edit, run commands, cat > "$root/index.wiki" <<'EOF'
or jump to the linked pages to test the plugin. = nuwiki sample wiki =
== Smoke test == %% Generated by the start-* dev launchers. A single fixture that exercises
%% every vimwiki feature nuwiki supports — open the linked pages and run
%% the plugin commands against them.
- [[Notes]] One page per feature group:
- [[diary/]]
- [ ] Toggle me with <C-Space> - [[Syntax]] — inline formatting, blocks, comments
- [ ] Or with :VimwikiToggleListItem - [[Lists]] — bullets, ordering, checkbox states, nesting
- [[Tables]] — alignment and spanning cells
- [[Links]] — every wikilink and URL form
- [[Notes]] — anchor targets for cross-page links
- [[diary/diary]] — the diary index
=== Heading level 3 ===
==== Heading level 4 ====
===== Heading level 5 =====
====== Heading level 6 ======
== Commands to try == == Commands to try ==
- :VimwikiTOC - :NuwikiTOC
- :VimwikiGenerateLinks - :NuwikiGenerateLinks
- :VimwikiCheckLinks - :NuwikiCheckLinks
- :VimwikiMakeDiaryNote - :NuwikiMakeDiaryNote
- :Vimwiki2HTMLBrowse
== Tags == :sample:smoke-test:sandbox:
:smoke-test:sandbox:
== Links ==
* [[Notes]]
* [[Notes#section-one]]
* https://example.com
EOF EOF
fi
if [[ ! -f "$WIKI_DIR/Notes.wiki" ]]; then cat > "$root/Syntax.wiki" <<'EOF'
cat > "$WIKI_DIR/Notes.wiki" <<'EOF' = Syntax showcase =
Back to [[index]].
== Inline formatting ==
*bold*, _italic_, *_bold italic_*, ~~strikethrough~~, `inline code`,
super^script^ and sub,,script,,, and inline math $e^{i\pi} + 1 = 0$.
== Keywords ==
TODO STARTED FIXME XXX DONE FIXED STOPPED
== Horizontal rule ==
----
== Blockquote ==
> A quoted line.
> A second quoted line.
== Definition list ==
Term:: Definition of the term.
Another:: Its definition.
== Code block ==
{{{python
def greet(name):
return f"hello {name}"
}}}
== Math block ==
{{$
\sum_{i=1}^{n} i = \frac{n(n+1)}{2}
}}$
== Comments ==
%% a single-line comment
%%+ a multi-line
comment block +%%
== Transclusion ==
{{file:image.png}}
{{image.png|alt text|width=120}}
EOF
cat > "$root/Lists.wiki" <<'EOF'
= Lists =
Back to [[index]].
== Unordered ==
- item with dash
- second
- nested under dash
* item with star
# item with hash
== Ordered ==
1. first
2. second
1. nested ordered
1) paren style
a) alpha
A) Alpha
i) roman
I) Roman
== Checkbox states ==
- [ ] empty (0%)
- [.] started (1-33%)
- [o] in progress (34-66%)
- [O] nearly done (67-99%)
- [X] done (100%)
- [-] rejected
== Nested with checkboxes ==
- [ ] parent task
- [X] done subtask
- [ ] pending subtask
- [ ] deep subtask
EOF
cat > "$root/Tables.wiki" <<'EOF'
= Tables =
Back to [[index]].
== Plain ==
| Name | Role |
| Alice | Author |
| Bob | Editor |
== Aligned ==
| Left | Center | Right |
|:-----|:------:|------:|
| a | b | c |
| d | e | f |
== Spanning cells ==
| Header | Span |
| cell | > |
| rowspan | value |
| \/ | value |
EOF
cat > "$root/Links.wiki" <<'EOF'
= Links =
Back to [[index]].
== Wikilinks ==
- [[Notes]]
- [[Notes|described]]
- [[Notes#Section one]]
- [[Notes#Section one|anchored + described]]
- [[/index]]
- [[diary/]]
- [[#Wikilinks]]
== Diary and interwiki ==
- [[diary:2026-05-30]]
- [[wiki1:index]]
- [[wn.MyWiki:index]]
== External and raw URLs ==
- [[https://example.com]]
- [[https://example.com|Example]]
- https://example.com
- mailto:gffranco@gmail.com
- file:///etc/hosts
EOF
cat > "$root/Notes.wiki" <<'EOF'
= Notes = = Notes =
A second page so [[index]] has somewhere to point. A page that other pages point at. Back to [[index]].
== Section one == == Section one ==
Anchor target for :checkhealth-style smoke tests. Anchor target for cross-page links.
== Section two ==
Another anchor target.
EOF EOF
cat > "$root/diary/diary.wiki" <<'EOF'
= Diary =
Back to [[/index]].
- [[2026-05-30]]
EOF
cat > "$root/diary/2026-05-30.wiki" <<'EOF'
= 2026-05-30 =
A diary entry. Back to [[diary]].
- [X] set up sample wiki
- [ ] review every feature page
EOF
}
seed_wiki() {
mkdir -p "$WIKI_DIR" "$WIKI_DIR/diary"
# Seed the whole showcase as a unit; skip when an index already exists
# so a re-run never clobbers edits made while testing.
if [[ -f "$WIKI_DIR/index.wiki" ]]; then
return
fi fi
write_sample_wiki "$WIKI_DIR"
} }
write_init() { write_init() {
+227 -37
View File
@@ -77,49 +77,239 @@ ensure_vim_lsp() {
clone_if_missing https://github.com/prabirshrestha/async.vim.git "$ASYNC_DIR" || true clone_if_missing https://github.com/prabirshrestha/async.vim.git "$ASYNC_DIR" || true
} }
# write_sample_wiki DIR — lay down a fixture that exercises every vimwiki
# feature nuwiki supports: one page per feature group plus a diary. Kept
# identical to the copy in start-nvim.sh so both launchers showcase the
# same surface. Heredocs use a quoted delimiter so `$math`, backticks,
# and backslashes land verbatim.
write_sample_wiki() {
local root="$1"
mkdir -p "$root" "$root/diary"
cat > "$root/index.wiki" <<'EOF'
= nuwiki sample wiki =
%% Generated by the start-* dev launchers. A single fixture that exercises
%% every vimwiki feature nuwiki supports — open the linked pages and run
%% the plugin commands against them.
One page per feature group:
- [[Syntax]] — inline formatting, blocks, comments
- [[Lists]] — bullets, ordering, checkbox states, nesting
- [[Tables]] — alignment and spanning cells
- [[Links]] — every wikilink and URL form
- [[Notes]] — anchor targets for cross-page links
- [[diary/diary]] — the diary index
=== Heading level 3 ===
==== Heading level 4 ====
===== Heading level 5 =====
====== Heading level 6 ======
== Commands to try ==
- :NuwikiTOC
- :NuwikiGenerateLinks
- :NuwikiCheckLinks
- :NuwikiMakeDiaryNote
:sample:smoke-test:sandbox:
EOF
cat > "$root/Syntax.wiki" <<'EOF'
= Syntax showcase =
Back to [[index]].
== Inline formatting ==
*bold*, _italic_, *_bold italic_*, ~~strikethrough~~, `inline code`,
super^script^ and sub,,script,,, and inline math $e^{i\pi} + 1 = 0$.
== Keywords ==
TODO STARTED FIXME XXX DONE FIXED STOPPED
== Horizontal rule ==
----
== Blockquote ==
> A quoted line.
> A second quoted line.
== Definition list ==
Term:: Definition of the term.
Another:: Its definition.
== Code block ==
{{{python
def greet(name):
return f"hello {name}"
}}}
== Math block ==
{{$
\sum_{i=1}^{n} i = \frac{n(n+1)}{2}
}}$
== Comments ==
%% a single-line comment
%%+ a multi-line
comment block +%%
== Transclusion ==
{{file:image.png}}
{{image.png|alt text|width=120}}
EOF
cat > "$root/Lists.wiki" <<'EOF'
= Lists =
Back to [[index]].
== Unordered ==
- item with dash
- second
- nested under dash
* item with star
# item with hash
== Ordered ==
1. first
2. second
1. nested ordered
1) paren style
a) alpha
A) Alpha
i) roman
I) Roman
== Checkbox states ==
- [ ] empty (0%)
- [.] started (1-33%)
- [o] in progress (34-66%)
- [O] nearly done (67-99%)
- [X] done (100%)
- [-] rejected
== Nested with checkboxes ==
- [ ] parent task
- [X] done subtask
- [ ] pending subtask
- [ ] deep subtask
EOF
cat > "$root/Tables.wiki" <<'EOF'
= Tables =
Back to [[index]].
== Plain ==
| Name | Role |
| Alice | Author |
| Bob | Editor |
== Aligned ==
| Left | Center | Right |
|:-----|:------:|------:|
| a | b | c |
| d | e | f |
== Spanning cells ==
| Header | Span |
| cell | > |
| rowspan | value |
| \/ | value |
EOF
cat > "$root/Links.wiki" <<'EOF'
= Links =
Back to [[index]].
== Wikilinks ==
- [[Notes]]
- [[Notes|described]]
- [[Notes#Section one]]
- [[Notes#Section one|anchored + described]]
- [[/index]]
- [[diary/]]
- [[#Wikilinks]]
== Diary and interwiki ==
- [[diary:2026-05-30]]
- [[wiki1:index]]
- [[wn.MyWiki:index]]
== External and raw URLs ==
- [[https://example.com]]
- [[https://example.com|Example]]
- https://example.com
- mailto:gffranco@gmail.com
- file:///etc/hosts
EOF
cat > "$root/Notes.wiki" <<'EOF'
= Notes =
A page that other pages point at. Back to [[index]].
== Section one ==
Anchor target for cross-page links.
== Section two ==
Another anchor target.
EOF
cat > "$root/diary/diary.wiki" <<'EOF'
= Diary =
Back to [[/index]].
- [[2026-05-30]]
EOF
cat > "$root/diary/2026-05-30.wiki" <<'EOF'
= 2026-05-30 =
A diary entry. Back to [[diary]].
- [X] set up sample wiki
- [ ] review every feature page
EOF
}
seed_wiki() { seed_wiki() {
if [[ "${NUWIKI_DEV_NO_SEED:-0}" == "1" ]]; then if [[ "${NUWIKI_DEV_NO_SEED:-0}" == "1" ]]; then
log "NUWIKI_DEV_NO_SEED=1 — skipping wiki seed (using $WIKI_DIR as-is)" log "NUWIKI_DEV_NO_SEED=1 — skipping wiki seed (using $WIKI_DIR as-is)"
return return
fi fi
mkdir -p "$WIKI_DIR" "$WIKI_DIR/diary" # Seed the whole showcase as a unit; skip when an index already exists
if [[ ! -f "$WIKI_DIR/index.wiki" ]]; then # so a re-run never clobbers edits made while testing.
cat > "$WIKI_DIR/index.wiki" <<'EOF' if [[ -f "$WIKI_DIR/index.wiki" ]]; then
= Welcome to nuwiki = return
This is a scratch wiki created by start-vim.sh. Edit, run commands,
or jump to the linked pages to test the plugin.
== Smoke test ==
- [[Notes]]
- [[diary/]]
- [ ] Toggle me with :VimwikiToggleListItem
- [ ] Inspect the LSP via :LspStatus
== Commands to try ==
- :VimwikiTOC
- :VimwikiGenerateLinks
- :VimwikiCheckLinks
- :VimwikiMakeDiaryNote
== Tags ==
:smoke-test:sandbox:
EOF
fi
if [[ ! -f "$WIKI_DIR/Notes.wiki" ]]; then
cat > "$WIKI_DIR/Notes.wiki" <<'EOF'
= Notes =
A second page so [[index]] has somewhere to point.
== Section one ==
Anchor target for cross-page link follows.
EOF
fi fi
write_sample_wiki "$WIKI_DIR"
} }
write_vimrc() { write_vimrc() {
-34
View File
@@ -1,34 +0,0 @@
#!/usr/bin/env bash
#
# test-personal-wiki.sh — open the user's real personal wiki via start-vim.sh.
#
# Reuses start-vim.sh's plumbing (binary build, vim-lsp clone, viminfo
# under the dev cache) but points the wiki root at ~/.vimwiki/personal_wiki
# and disables seed_wiki so we don't drop a scratch `Notes.wiki` into your
# real notes.
#
# Useful when reproducing a user-reported bug against actual content rather
# than the seeded smoke-test wiki. State (viminfo/sessions) still lives
# under $XDG_CACHE_HOME/nuwiki-dev/ so your real Vim install stays untouched.
#
# Usage:
# ./development/test-personal-wiki.sh # open index.wiki
# ./development/test-personal-wiki.sh path/to/note.wiki # open a specific file
# NUWIKI_PERSONAL_WIKI=/other/path ./development/test-personal-wiki.sh
# NUWIKI_DEV_SKIP_BUILD=1 ./development/test-personal-wiki.sh # reuse the cached binary
set -euo pipefail
REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
WIKI_DIR="${NUWIKI_PERSONAL_WIKI:-$HOME/.vimwiki/personal_wiki}"
if [[ ! -d "$WIKI_DIR" ]]; then
echo "test-personal-wiki: $WIKI_DIR does not exist" >&2
echo "set NUWIKI_PERSONAL_WIKI to point at your wiki, or create the default path" >&2
exit 1
fi
export NUWIKI_DEV_WIKI="$WIKI_DIR"
export NUWIKI_DEV_NO_SEED=1
exec "$REPO_ROOT/development/start-vim.sh" "$@"