diff --git a/.github/workflows/deploy-staging.yml b/.github/workflows/deploy-staging.yml deleted file mode 100644 index 7ba357a..0000000 --- a/.github/workflows/deploy-staging.yml +++ /dev/null @@ -1,32 +0,0 @@ -name: Deploy CI/CD to Staging - -on: - push: - branches: - - staging - -jobs: - deploy: - runs-on: ubuntu-latest - timeout-minutes: 90 - - steps: - - name: Deploy to Staging - uses: appleboy/ssh-action@0ff4204d59e8e51228ff73bce53f80d53301dee2 # v1.2.5 - with: - host: ${{ secrets.STAGING_HOST }} - username: ${{ secrets.USERNAME }} - key: ${{ secrets.STAGING_KEY }} - port: 22 - command_timeout: 30m - script_stop: true - script: | - set -x - cd /home/frappe/frappe-bench/apps/wiki - git pull upstream staging - cd /home/frappe/frappe-bench - bench setup requirements wiki - bench migrate - bench build --app wiki - bench clear-cache - bench restart diff --git a/.github/workflows/deploy-test-production.yml b/.github/workflows/deploy-test-production.yml deleted file mode 100644 index 8190809..0000000 --- a/.github/workflows/deploy-test-production.yml +++ /dev/null @@ -1,32 +0,0 @@ -name: Deploy CI/CD to Test production - -on: - push: - branches: - - test-production - -jobs: - deploy: - runs-on: ubuntu-latest - timeout-minutes: 90 - - steps: - - name: Deploy to Test Production - uses: appleboy/ssh-action@0ff4204d59e8e51228ff73bce53f80d53301dee2 # v1.2.5 - with: - host: ${{ secrets.STAGING_HOST }} - username: ${{ secrets.USERNAME }} - key: ${{ secrets.STAGING_KEY }} - port: 22 - command_timeout: 30m - script_stop: true - script: | - set -x - cd /home/frappe/test-production/apps/wiki - git pull upstream test-production - cd /home/frappe/test-production - bench setup requirements wiki - bench migrate - bench build --app wiki - bench clear-cache - bench restart diff --git a/README.md b/README.md index 78d360a..8961335 100644 --- a/README.md +++ b/README.md @@ -10,8 +10,8 @@ ---
- Wiki App built on the Frappe Framework | Try on Frappe Cloud - + Wiki App built on the Frappe Framework | Try on Frappe Cloud + \ [![Wiki](https://img.shields.io/endpoint?url=https://cloud.cypress.io/badge/simple/w2jgcb/master&style=flat&logo=cypress)](https://cloud.cypress.io/projects/w2jgcb/runs) [![CI](https://github.com/frappe/wiki/actions/workflows/ci.yml/badge.svg?event=push)](https://github.com/frappe/wiki/actions/workflows/ci.yml) @@ -19,28 +19,250 @@ ## Introduction -Frappe Wiki is an Open Source [Wiki](https://en.wikipedia.org/wiki/Wiki) app built on the Frappe Framework. It is well suited to serve dynamic, text-heavy content like documentation and knowledge base. It allows publishing small changes and even new pages on the fly without downtime. It also maintains revision history and has a change approval mechanism. +Frappe Wiki is an open source wiki app built on the Frappe Framework. It is designed for dynamic, text-heavy content such as internal documentation, knowledge bases, SOPs, and structured help content. The app supports page-level publishing, revision history, sidebars grouped by wiki space, and search across public documentation. + +This repository is the `wiki` app itself. It contains the DocTypes, website routes, search indexing logic, sidebar rendering, and end-to-end tests that drive the user experience. + +## What The App Does + +Core capabilities visible in the current codebase: + +1. Create and publish wiki pages. +2. Organize pages into wiki spaces and sidebar groups. +3. Track page revisions and review changes through wiki page patches. +4. Render markdown-like rich content into public website routes. +5. Search pages through Redisearch or Frappe web search fallback. +6. Manage wiki settings such as default space, logos, search bar visibility, dark mode, and sidebar display. ## Installation ```bash # get app -$ bench get-app https://github.com/frappe/wiki +bench get-app https://github.com/frappe/wiki # install on site -$ bench --site sitename install-app wiki +bench --site sitename install-app wiki +``` + +If you are working in a multi-app bench, install `wiki` into the target site after Frappe is already available in the bench. + +## Local Development + +Typical local flow: + +```bash +# from bench root +bench start +``` + +In another shell: + +```bash +bench --site sitename migrate +bench --site sitename clear-cache +``` + +When editing front-end assets, keep the bench running so route and asset changes are visible quickly. + +## Architecture Overview + +The app is structured around a few main subsystems: + +### 1. Website Routing + +- `wiki/www/wiki.py` handles the `/wiki` entry route. +- It redirects users to the default wiki space configured in `Wiki Settings`. +- Individual pages are served through the website generator behavior of `Wiki Page`. + +### 2. Content Model + +- `Wiki Page` is the primary content record. +- `Wiki Space` groups pages into logical sections. +- `Wiki Group Item` controls sidebar grouping and ordering. +- `Wiki Page Revision` and `Wiki Page Revision Item` preserve edit history. +- `Wiki Page Patch` handles proposed edits and approval flow. + +### 3. Rendering Pipeline + +- `wiki/wiki/doctype/wiki_page/wiki_page.py` sanitizes HTML before save. +- Page content is converted to HTML for rendering. +- Table of contents HTML is generated from page headings when enabled in settings. +- Sidebar HTML is rendered dynamically and cached. + +### 4. Search + +- `wiki/wiki/doctype/wiki_page/search.py` provides page search. +- If Redisearch is disabled, the app falls back to Frappe web search. +- If Redisearch is enabled, indexes are maintained per wiki space route. + +### 5. Cache Invalidation + +Sidebar cache and search index rebuilds are triggered by: + +- page updates +- page deletion +- wiki space updates +- wiki settings changes that affect sidebar visibility +- post-migrate hook +- hourly scheduler hook + +## Repository Layout + +```text +wiki/ +├── wiki/ +│ ├── config/ +│ ├── doctype/ +│ │ ├── migrate_to_wiki/ +│ │ ├── wiki_group_item/ +│ │ ├── wiki_page/ +│ │ ├── wiki_page_patch/ +│ │ ├── wiki_page_revision/ +│ │ ├── wiki_page_revision_item/ +│ │ ├── wiki_settings/ +│ │ ├── wiki_sidebar/ +│ │ └── wiki_space/ +│ ├── public/ +│ │ ├── js/ +│ │ └── scss/ +│ ├── templates/ +│ └── www/ +├── cypress/ +│ ├── e2e/ +│ └── support/ +├── .github/ +├── pyproject.toml +├── package.json +└── README.md +``` + +## Wiki Page Hierarchy + +The current hierarchy is route-driven and space-driven rather than filesystem-driven. + +High-level flow: + +```text +Wiki Settings + -> default_wiki_space + -> Wiki Space + -> wiki_sidebars + -> Wiki Group Item entries + -> Wiki Page records + -> rendered website routes +``` + +Sidebar and space behavior in practice: + +- a wiki space owns grouped sidebar entries +- each group points to one or more wiki pages +- page routes usually live under the wiki space route +- when a space route changes, child page routes are rewritten + +## Customization Notes + +Current local/customized operational behavior visible in this repository: + +- branch workflow assumes `staging`, `test-production`, and `version-15` +- repo automation includes agent-trigger workflows in `.github/workflows/` +- CI hardening and repo-standardization work is being added through task branches + +When updating from upstream or porting changes: + +1. Diff workflow files before overwriting them. +2. Preserve branch-specific automation tied to ONE-F-M deployment flow. +3. Re-check repo-root documentation after merges from upstream. + +## Editing and Review Flow + +The code currently supports a patch-driven edit flow: + +1. A page exists as a `Wiki Page`. +2. Edits are submitted through the page update path. +3. The change becomes a `Wiki Page Patch`. +4. Draft edits stay in draft flow. +5. Review edits move through an approval path. +6. Approved content becomes part of the page and revision history. + +Important implementation note: + +The code clearly exposes `Draft` and `Under Review` patch states. If you are documenting or extending lifecycle behavior, do not claim an `Archived` state unless you add it to the code first. + +## Testing + +### Server Tests + +Run app tests from the bench: + +```bash +bench --site sitename run-tests --app wiki +``` + +Useful variants: + +```bash +bench --site sitename run-tests --doctype "Wiki Page" +bench --site sitename run-tests --doctype "Wiki Space" ``` -Note: Wiki's master branch does not support v13 Frappe / ERPNext -## Features +### Cypress E2E Tests + +The repository already includes Cypress coverage for: -1. Create Wiki Pages -2. Author content in Rich Text -3. Set-up Controlled Wiki Updates -5. Add attachments -6. Table of Contents -7. Caching -8. Custom Script Support via `Wiki Settings` +- creating a wiki page +- editing a wiki page +- deleting a wiki page +- creating a sidebar group +- deleting an empty sidebar group + +Typical usage: + +```bash +npx cypress open +``` + +or: + +```bash +npx cypress run +``` + +## Contributing Guidelines + +When contributing to this repository: + +1. Keep route changes deliberate. Wiki URLs are user-facing and breaking them has documentation impact. +2. Clear or rebuild cache/index paths when changing sidebar or search logic. +3. Preserve permission checks for non-public content. +4. Keep changes to `Wiki Page`, `Wiki Space`, and patch/revision flows well-tested. +5. Update Cypress coverage if the editing or sidebar UI changes. +6. Prefer focused PRs scoped to one behavior at a time. + +## Security Notes + +Security-sensitive areas in this app: + +- HTML sanitization in `Wiki Page.sanitize_html()` +- guest-read logic through `allow_guest` +- redirect-to-login behavior for unauthorized access +- public search endpoints that must stay aligned with page visibility + +Do not bypass these paths casually. Search and rendering can become data-leak vectors if permission assumptions drift. + +## CI / Automation + +Current repo work includes CI additions for: + +- test gating on PRs +- linting +- type checking +- coverage reporting + +If a workflow change is needed, keep the branch targets aligned with the repo’s protected branch strategy: + +- `staging` +- `test-production` +- `version-15` ## Screenshots @@ -50,6 +272,12 @@ Note: Wiki's master branch does not support v13 Frappe / ERPNext ### 2. Edit Page wiki-edit +## Support + +- GitHub Issues for bugs and feature requests +- Frappe Forum for general framework questions +- Repo-local `AGENTS.md` for operator/agent implementation context + #### License MIT