Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
88 commits
Select commit Hold shift + click to select a range
617b0eb
docs: add polished static user guide and Pages build
WilliamWang1721 Sep 24, 2026
5aba1a1
docs: complete user documentation
WilliamWang1721 Sep 25, 2026
3455dcc
docs: refine navigation and add project guides
WilliamWang1721 Sep 25, 2026
6d266d4
Merge branch 'main' into docs/complete-user-guide-20260924
WilliamWang1721 Sep 26, 2026
90931c0
Merge upstream main into docs/complete-user-guide-20260924
WilliamWang1721 Sep 26, 2026
3f7f9a8
Merge upstream main into docs/complete-user-guide-20260924
WilliamWang1721 Sep 26, 2026
ac03fe6
Merge upstream main into docs/complete-user-guide-20260924
WilliamWang1721 Sep 26, 2026
6499768
Merge upstream main into docs/complete-user-guide-20260924
WilliamWang1721 Sep 27, 2026
bca1c5e
Merge upstream main into docs/complete-user-guide-20260924
WilliamWang1721 Sep 27, 2026
6744f44
Merge upstream main into docs/complete-user-guide-20260924
WilliamWang1721 Sep 28, 2026
721d0df
Merge upstream main into docs/complete-user-guide-20260924
WilliamWang1721 Sep 28, 2026
f8f4722
Merge upstream main into docs/complete-user-guide-20260924
WilliamWang1721 Sep 28, 2026
d3f2fba
Merge upstream main into docs/complete-user-guide-20260924
WilliamWang1721 Sep 28, 2026
6469f99
docs: clean static guide output and filenames
WilliamWang1721 Sep 28, 2026
920079e
Merge remote-tracking branch 'origin/main' into codex/pr291-sync-77e-…
WilliamWang1721 Sep 28, 2026
d67436a
docs: align contributor guide with current CI policy
WilliamWang1721 Sep 28, 2026
a80a7cb
Merge upstream main into docs/complete-user-guide-20260924
WilliamWang1721 Sep 28, 2026
75533d9
Merge upstream main into docs/complete-user-guide-20260924
WilliamWang1721 Sep 30, 2026
db852a1
fix(docs): follow agent integration module move
WilliamWang1721 Sep 30, 2026
0bc72ee
fix(docs): follow hook settings module move
WilliamWang1721 Sep 30, 2026
c84e58b
docs: describe current path-based native CI coverage
WilliamWang1721 Sep 30, 2026
97bfa96
Merge latest upstream main for strict PR validation
WilliamWang1721 Sep 30, 2026
901dbe8
Merge latest upstream main while preserving reviewed feature fixes
WilliamWang1721 Sep 30, 2026
1f42b3f
Merge current upstream mobile changes without expanding feature scope
WilliamWang1721 Sep 30, 2026
24ea816
docs: cover current completion, encrypted backups and Android pairing
WilliamWang1721 Sep 30, 2026
8141882
Merge upstream 2.1.0 and theme improvements while retaining verified …
WilliamWang1721 Sep 30, 2026
4a4d314
Merge upstream main into docs/complete-user-guide-20260924
WilliamWang1721 Oct 1, 2026
ae87ea4
Merge current upstream main, preserving reviewed desktop feature beha…
WilliamWang1721 Oct 1, 2026
5656fab
Merge upstream main into docs/complete-user-guide-20260924
WilliamWang1721 Oct 1, 2026
9f1742a
Merge upstream main into docs/complete-user-guide-20260924
WilliamWang1721 Oct 1, 2026
7a7ba24
Merge upstream main into docs/complete-user-guide-20260924
WilliamWang1721 Oct 1, 2026
e3bed6f
Merge upstream main into PR #291
WilliamWang1721 Oct 1, 2026
5c0fbb8
Merge upstream main into PR #291
WilliamWang1721 Oct 1, 2026
2a7ea45
Merge upstream main into PR #291
WilliamWang1721 Oct 3, 2026
1655aa2
Merge upstream main into PR #291
WilliamWang1721 Oct 3, 2026
0c55904
Merge upstream main into PR #291
WilliamWang1721 Oct 3, 2026
53a9251
Merge upstream main into docs/complete-user-guide-20260924
WilliamWang1721 Oct 4, 2026
28afaf9
Merge upstream main into docs/complete-user-guide-20260924
WilliamWang1721 Oct 4, 2026
c001010
Merge branch 'main' into docs/complete-user-guide-20260924
WilliamWang1721 Oct 6, 2026
cddce85
docs(site): add supported-agents guide, built-in colour themes and 2.…
WilliamWang1721 Oct 7, 2026
4c8a724
fix(docs-site): suspend transitions while switching the colour theme
WilliamWang1721 Oct 7, 2026
25da114
Merge branch 'main' into docs/complete-user-guide-20260924
WilliamWang1721 Oct 7, 2026
ecc81bc
fix(docs-site): read the default version in the browser check
WilliamWang1721 Oct 7, 2026
f795fff
Merge branch 'main' into docs/complete-user-guide-20260924
WilliamWang1721 Oct 8, 2026
56286ec
Merge upstream main into docs/complete-user-guide-20260924
WilliamWang1721 Oct 11, 2026
4e2f519
Merge upstream main into docs/complete-user-guide-20260924
WilliamWang1721 Oct 11, 2026
240d50b
Merge upstream main into docs/complete-user-guide-20260924
WilliamWang1721 Oct 13, 2026
db79151
Merge upstream main into docs/complete-user-guide-20260924
WilliamWang1721 Oct 13, 2026
24f3713
Merge upstream main into docs/complete-user-guide-20260924
WilliamWang1721 Oct 14, 2026
3330699
Merge upstream main into docs/complete-user-guide-20260924
WilliamWang1721 Oct 14, 2026
ba9a78d
Merge upstream main into docs/complete-user-guide-20260924
WilliamWang1721 Oct 14, 2026
a34b9cb
Merge upstream main into docs/complete-user-guide-20260924
WilliamWang1721 Oct 15, 2026
a44e2ae
Merge upstream main into docs/complete-user-guide-20260924
WilliamWang1721 Oct 15, 2026
8c966f4
Merge upstream main into docs/complete-user-guide-20260924
WilliamWang1721 Oct 16, 2026
e070913
Merge upstream main into docs/complete-user-guide-20260924
WilliamWang1721 Oct 17, 2026
3a0ea2b
Merge upstream main into docs/complete-user-guide-20260924
WilliamWang1721 Oct 19, 2026
ce6eb49
Merge upstream main into docs/complete-user-guide-20260924
WilliamWang1721 Oct 21, 2026
c1985ac
Merge upstream main into docs/complete-user-guide-20260924
WilliamWang1721 Oct 21, 2026
6dbf8f5
Merge upstream main into docs/complete-user-guide-20260924
WilliamWang1721 Oct 22, 2026
d59d9b6
Merge upstream main into docs/complete-user-guide-20260924
WilliamWang1721 Oct 23, 2026
3890de5
Merge upstream main into docs/complete-user-guide-20260924
WilliamWang1721 Oct 23, 2026
5d03126
Merge upstream main into docs/complete-user-guide-20260924
WilliamWang1721 Oct 23, 2026
3e9ed63
Merge upstream main into docs/complete-user-guide-20260924
WilliamWang1721 Oct 24, 2026
cecb16c
Merge upstream main into docs/complete-user-guide-20260924
WilliamWang1721 Oct 24, 2026
9fde722
Merge upstream main into docs/complete-user-guide-20260924
WilliamWang1721 Oct 25, 2026
1699c19
Merge upstream main into docs/complete-user-guide-20260924
WilliamWang1721 Oct 26, 2026
c7f6b4f
Merge upstream main into docs/complete-user-guide-20260924
WilliamWang1721 Oct 26, 2026
65199ab
Merge upstream main into docs/complete-user-guide-20260924
WilliamWang1721 Oct 27, 2026
502a74d
Merge upstream main into docs/complete-user-guide-20260924
WilliamWang1721 Oct 28, 2026
3d84cbb
Merge upstream main into docs/complete-user-guide-20260924
WilliamWang1721 Oct 28, 2026
b00d370
Merge upstream main into docs/complete-user-guide-20260924
WilliamWang1721 Oct 30, 2026
ae98526
Merge upstream main into docs/complete-user-guide-20260924
WilliamWang1721 Oct 31, 2026
613d04f
Merge upstream main into docs/complete-user-guide-20260924
WilliamWang1721 Nov 1, 2026
e87ea27
Merge upstream main into docs/complete-user-guide-20260924
WilliamWang1721 Nov 2, 2026
5fe60ca
Merge upstream main into docs/complete-user-guide-20260924
WilliamWang1721 Nov 3, 2026
4c007c6
Merge upstream main into docs/complete-user-guide-20260924
WilliamWang1721 Nov 4, 2026
82429e9
Merge upstream main into docs/complete-user-guide-20260924
WilliamWang1721 Nov 4, 2026
cfdefd1
Merge upstream main into docs/complete-user-guide-20260924
WilliamWang1721 Nov 4, 2026
f722f63
Merge upstream main into docs/complete-user-guide-20260924
WilliamWang1721 Nov 17, 2026
0cfff65
docs(site): follow the nebula to pebrel crate and directory rename
WilliamWang1721 Nov 17, 2026
b5c3f28
Merge upstream main into docs/complete-user-guide-20260924
WilliamWang1721 Nov 17, 2026
572d52d
Merge upstream main into docs/complete-user-guide-20260924
WilliamWang1721 Nov 19, 2026
579d0f5
Merge upstream main into docs/complete-user-guide-20260924
WilliamWang1721 Nov 19, 2026
36569dd
Merge upstream main into docs/complete-user-guide-20260924
WilliamWang1721 Nov 20, 2026
217935a
Merge upstream main into docs/complete-user-guide-20260924
WilliamWang1721 Nov 20, 2026
640cdc4
Merge upstream main into docs/complete-user-guide-20260924
WilliamWang1721 Nov 21, 2026
3a5ac5d
Merge upstream main into docs/complete-user-guide-20260924
WilliamWang1721 Nov 21, 2026
0df1104
Merge upstream main into docs/complete-user-guide-20260924
WilliamWang1721 Nov 21, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
65 changes: 65 additions & 0 deletions .github/workflows/docs-site.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,65 @@
name: User documentation
on:
pull_request:
paths: ['docs/site/**', 'docs/screenshots/**', '.github/workflows/docs-site.yml']
push:
branches: [main, 'docs/**']
paths: ['docs/site/**', 'docs/screenshots/**', '.github/workflows/docs-site.yml']
workflow_dispatch:
permissions:
contents: read
concurrency:
group: docs-${{ github.ref }}
cancel-in-progress: true
jobs:
build:
permissions:
contents: read
pages: read
runs-on: ubuntu-24.04
timeout-minutes: 10
steps:
- uses: actions/checkout@v4
with:
persist-credentials: false
- uses: actions/setup-python@v5
with:
python-version: '3.13'
- name: Install documentation build tools
run: pip install -r docs/site/requirements.txt playwright==1.57.0
- name: Check links, page structure and search coverage
run: python -m unittest discover -s docs/site -p test_site.py
- name: Resolve the configured Pages URL
if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request' && vars.PEBREL_DOCS_PAGES_ENABLED == 'true'
id: pages
uses: actions/configure-pages@v5
- name: Build portable static site
env:
DOCS_BASE_URL: ${{ vars.PEBREL_DOCS_BASE_URL || steps.pages.outputs.base_url }}
run: python docs/site/build.py --base-url "$DOCS_BASE_URL"
- name: Install browser
run: python -m playwright install --with-deps chromium
- name: Check desktop, mobile, keyboard and reduced-motion behavior
run: python docs/site/check_browser.py
- uses: actions/upload-artifact@v4
if: always()
with:
name: docs-browser-results
path: docs-browser-results/
if-no-files-found: ignore
- uses: actions/upload-pages-artifact@v4
with:
path: docs/site/dist
deploy:
if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request' && vars.PEBREL_DOCS_PAGES_ENABLED == 'true'
needs: build
runs-on: ubuntu-24.04
permissions:
pages: write
id-token: write
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
steps:
- uses: actions/deploy-pages@v4
id: deployment
76 changes: 76 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -152,3 +152,79 @@ dist-pack-*/

NebulaTerminal-*/
*-preview-package/

# Published static user guide: exact reviewed source allowlist.
!/docs/site/
!/docs/site/assets/
!/docs/site/content/
!/docs/site/README.md
!/docs/site/assets/site.css
!/docs/site/assets/site.js
!/docs/site/build.py
!/docs/site/palettes.py
!/docs/site/check_browser.py
!/docs/site/content/index.md
!/docs/site/content/installation.md
!/docs/site/content/quickstart.md
!/docs/site/requirements.txt
!/docs/site/site.json
!/docs/site/template.html
!/docs/site/test_site.py

!/docs/site/content/workspace.md
!/docs/site/content/shells.md
!/docs/site/content/clipboard.md
!/docs/site/content/completions.md
!/docs/site/content/palette.md
!/docs/site/content/commands.md
!/docs/site/content/navigation.md
!/docs/site/content/keyboard.md
!/docs/site/content/broadcast.md
!/docs/site/content/sessions.md
!/docs/site/content/layouts.md
!/docs/site/content/quick-terminal.md
!/docs/site/content/ssh.md
!/docs/site/content/ssh-library.md
!/docs/site/content/ssh-auth.md
!/docs/site/content/ssh-routing.md
!/docs/site/content/sftp.md
!/docs/site/content/files.md
!/docs/site/content/vcs.md
!/docs/site/content/documents.md
!/docs/site/content/images.md
!/docs/site/content/remote-edit.md
!/docs/site/content/ai-start.md
!/docs/site/content/hooks.md
!/docs/site/content/ai-history.md
!/docs/site/content/agents.md
!/docs/site/content/send-to-chat.md
!/docs/site/content/appearance.md
!/docs/site/content/themes.md
!/docs/site/content/backgrounds.md
!/docs/site/content/fonts.md
!/docs/site/content/notifications.md
!/docs/site/content/interaction.md
!/docs/site/content/configuration.md
!/docs/site/content/network.md
!/docs/site/content/runtime.md
!/docs/site/content/settings.md
!/docs/site/content/updates.md
!/docs/site/content/migration.md
!/docs/site/content/privacy.md
!/docs/site/content/troubleshooting.md
!/docs/site/screenshots.json
!/docs/site/third-party-notices.txt
!/docs/site/content/terminal-basics.md
!/docs/site/content/wsl.md
!/docs/site/content/ssh-config.md
!/docs/site/content/git-conflicts.md
!/docs/site/content/svn.md
!/docs/site/content/markdown-editing.md
!/docs/site/content/config-examples.md
!/docs/site/content/agent-worktrees.md

!/docs/site/content/readme.md
!/docs/site/content/contributing.md

!/docs/site/content/backups.md
!/docs/site/content/mobile.md
80 changes: 80 additions & 0 deletions architecture/notes/docs/site/2026-09-24-static-user-guide.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,80 @@
# Static user guide build boundary

## Status

Proposed with the documentation-site pull request.

## Context

The desktop application needs a navigable user manual that can be reviewed in a
fork, published through repository Pages, and read without a running service.
Desktop builds must not acquire a web-toolchain dependency.

## Evidence

- [Builder](../../../../docs/site/build.py) converts reviewed Markdown into HTML.
- [Workflow](../../../../.github/workflows/docs-site.yml) builds independently of Cargo.
- [Checks](../../../../docs/site/test_site.py) cover references and search coverage.
- [Operations](../../../../docs/site/README.md) describes Pages activation.

## Decision

Keep the site under `docs/site`, with build-only pinned Markdown and highlighting
libraries. Emit independent HTML pages, relative asset links and a local search
index. Use system fonts and repository-owned application imagery. Production
Pages deployment requires explicit repository opt-in and only runs from `main`.

## Rejected alternatives

A client-only application would make basic reading depend on JavaScript. A
hosted search service would add a credential and network dependency. A second
large frontend framework is unnecessary for Markdown, navigation and search.

## Consequences

Markdown and navigation remain separately reviewable. Rich HTML is trusted
repository content, not an input format for arbitrary visitors. The build has no
server-side user input and does not affect the desktop runtime. Captured app
images require a separate native environment; browser screenshots verify only
the guide's own interface.

## Validation

Local structural tests and the independent browser workflow exercise generated
links, search, copying, theme persistence, mobile navigation and no-script reading.
CI results, rather than the presence of workflow files, establish run status.

## Supersedes

None.

## Revisit when

Multiple maintained languages or versioned manuals make the current navigation
manifest insufficient, or the small local search index no longer meets users'
needs. Re-evaluate on measured behavior rather than adding services in advance.

## Colour themes (2026-10-07)

The guide takes its colours from the application's built-in themes instead of a
site-specific palette, so the documentation reads as part of the product and
readers can choose the theme they already use. `docs/site/palettes.py` parses the
catalog from `nebula_settings/src/themes.rs` at build time; the build fails when
that source changes shape. A hand-copied colour table was rejected because it would
drift from the application. A fixed light/dark pair was rejected because the
application ships sixteen themes and a toggle cannot express them. Where a theme's
accent or muted colour is too faint for text, the site darkens or lightens it toward
the theme foreground until it reaches 4.5:1; the application's own colours are
unchanged. The choice is stored in browser storage only.

## Release baseline (2026-10-07)

The base pages were re-audited against the `v2.1.1` tag and the manifest now records
that version and commit for every page; the earlier page-level `main` overrides were
removed. The tag, not `main`, is the baseline because the guide describes what readers
can install: `main` carries features that are not in any release. Pages whose behaviour
changed between 1.9.1 and 2.1.1 were updated from the code at the tag (platform
integrations on macOS and Linux, Windows ARM64 installer, release asset names, update
channels, settings navigation) and from the release notes for 2.0.0, 2.1.0 and 2.1.1.
Differences that are only translation refactors were not treated as behaviour changes.

Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
114 changes: 114 additions & 0 deletions docs/site/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,114 @@
# Pebrel user documentation

A Chinese user guide built from Markdown into standalone HTML, with local search,
keyboard navigation, light/dark themes, copy controls and image zoom. The build
uses existing repository screenshots; it does not redistribute font files or
change the desktop application's dependencies.

## Build and check

```sh
python -m pip install -r docs/site/requirements.txt
python docs/site/build.py
python -m unittest discover -s docs/site -p test_site.py
python -m http.server --directory docs/site/dist 8000
```

For the browser smoke check, install `playwright==1.57.0`, run
`python -m playwright install chromium`, then `python docs/site/check_browser.py`.
The check serves the site under `/pebrel/`, exercising project-site path handling.
`CHROMIUM_PATH` optionally selects an existing Chromium executable.

The manifest currently contains 56 user-facing guides, organized by tasks rather
than implementation modules. Source links are pinned to the documented commit.

The documented baseline is the `v2.1.1` release (commit `d574856`). Pages were checked
against that tag, not against later `main`: UI labels, platform availability and file
names such as release assets follow what 2.1.1 shipped. When a later release changes a
page, update that page, its evidence and `site.json` together, or record a page-level
`version` and `source_commit` as described below.

The generated `dist/` is disposable and ignored. Publish that directory's contents,
not this source directory. Open `index.html` directly for offline reading; browser
clipboard policies may require HTTP(S), in which case select and copy the text.
Search loads a local JavaScript index rather than requiring a backend or CDN.

## Colour themes

The site uses the desktop application's own palettes. `palettes.py` parses the 16
built-in themes from `pebrel_settings/src/themes.rs` (and their names from
`pebrel_app/src/display/ui/theme.rs`) at build time and writes `assets/palettes.css`
plus the syntax colours in `assets/highlight.css`. Nothing is copied by hand, so a
theme added or retuned in the application reaches the site on the next build, and the
build fails if the source no longer has the expected shape.

Readers pick a theme from the palette button in the header. **Follow system** mirrors the
application's default pair, Nord Light and Nord. The choice is stored in the browser
only. Accent, muted and syntax colours are nudged toward the theme's foreground when
they would fall below a 4.5:1 contrast ratio on the page or code surface; the tests
check this for every theme.

## GitHub Pages

The `User documentation` workflow builds and checks documentation on matching
pull requests and documentation-branch pushes. A PR never deploys the production
site. It publishes a Pages artifact and browser screenshots for review.

A repository administrator must first choose **Settings → Pages → Source → GitHub
Actions**. Set the repository variable `PEBREL_DOCS_PAGES_ENABLED` to `true` to opt
in to deployment from `main`. On production builds, the workflow reads the
configured Pages URL for canonical links, the sitemap and the 404 home link.
Optionally override `PEBREL_DOCS_BASE_URL` with the public
site root, including the repository prefix and trailing slash, such as
`https://kuddev.github.io/pebrel/`, for canonical links and a sitemap. For a custom
domain, supply that domain's root instead. The workflow does not change repository
settings, DNS or domain ownership.

After the change is merged, the workflow deploys on a matching `main` push; it can
also be run manually from `main`. Fork builds do not deploy unless their owner
separately enables the same opt-in variable and Pages setting.

## Maintain content

`site.json` owns navigation, the documented version, the source commit and each
page's evidence paths. A page may override `version` and `source_commit` when
a newer feature has been audited; its displayed version and evidence links then
use that snapshot without relabeling older guides. State the boundary in the page
body too: an audited `main` feature is not a claim of release availability.
Pages live in `content/`. Use Markdown links such as
`[Installation](installation.md)`: the builder resolves them for nested HTML paths.
Use `@ROOT@` for local image paths in rich HTML. Raw HTML is allowed for trusted,
reviewed repository content only; this is not an untrusted Markdown service.

The build copies images named in `site.json` from `docs/screenshots/` and the
application icon from `extra/logo/nebula.png`. Caption old repository captures as
such. Newly captured application images must state their platform and version;
do not label a mockup or a documentation-page screenshot as an application capture.

After verifying a feature change, update the relevant page and its evidence.
Lead with the task, identify the actual menu or shortcut, explain the result,
and place cautions beside the affected operation. Use visible entry points from
the page's documented snapshot: retained implementation code is not by itself
evidence of an available UI feature. Keep
implementation rationale out of the user guide. Add each new public source
file to the exact `.gitignore` allowlist rather than opening the whole `docs/`
subtree. The build checks that evidence paths exist; existence alone is not proof
that every sentence has been audited.

## Application screenshot provenance

`screenshots.json` records the original source and digest of every bundled image.
Most figures reuse the existing repository images and do not imply a particular
capture version. The macOS installation figure is the unchanged native application
capture from the official 1.9.1 release run `35961098033`, artifact
`stable-evidence-macos-aarch64` (`10792632932`). Its launch report identifies source
commit `e9e83d83a63ca9cc885857439f7f6826c1cbabaf`, whose tree matches the documented
main snapshot, and reports macOS 26.6.2 / aarch64. This was an existing upstream CI
run, not a new run dispatched by the documentation task. Its test message is
captioned as such; it is not presented as default application content.

For future updates, inspect matching-version release evidence before replacing a
figure. Review the actual image, source commit and launch report, remove unrelated
personal content when necessary, and record any modification. Rebuild after
updating both the image manifest and provenance. Browser captures prove only the
documentation website's layout, not native application behavior.
Loading
Loading