Building an AnduinOS-Specific Modern Help App

[siyamsec-lab]

Hi everyone,

I wanted to share something I’ve been working on for AnduinOS: a custom Help application built with GTK4 and Libadwaita, designed specifically with the AnduinOS experience in mind.

The idea came from looking at the current Help experience and asking a simple question:

What would a Help application look like if it were designed specifically around the AnduinOS desktop experience rather than being a generic GNOME application?

What I’m building

I’m currently developing a modern Help app using:

• Python
• GTK4
• Libadwaita
• Native GNOME/AnduinOS design principles
• A structure that can accommodate AnduinOS-specific documentation

The application is inspired by the general simplicity of GNOME Help, but I’m experimenting with a more customized experience for AnduinOS.

The goal isn't to move away from GNOME's design language. Instead, I want the application to feel like a natural part of AnduinOS while still respecting the GTK4/Libadwaita ecosystem.

Why a custom Help app?

AnduinOS has its own identity, documentation, workflows, and user experience.

As AnduinOS continues to develop, I think there is value in having a Help application that can eventually explain things such as:

• AnduinOS-specific features
• Desktop customization
• System settings
• First-time setup
• Common troubleshooting
• AnduinOS applications and tools
• Documentation for features that aren't part of standard GNOME
• Links to relevant AnduinOS resources

This could make the Help experience more tightly integrated with the operating system itself.

What I'm considering

At this stage, I'm treating this as a prototype and Show & Tell, not as a finished replacement.

Depending on feedback, there are several possible directions:

1. Keep it as an experimental project.
2. Develop it into an AnduinOS-specific Help application.
3. Use it alongside the existing GNOME Help application.
4. If it becomes mature enough and the maintainers agree, consider using it as the default Help experience in AnduinOS.

I don't want to decide that part in isolation. I'd rather get feedback from the AnduinOS community first.

Design goals

Some of the things I'm aiming for are:

1. Native experience

The app should feel like it belongs on an AnduinOS desktop rather than looking like a separate third-party application.

2. Simple navigation

Users should be able to find documentation without having to understand the underlying Linux/GNOME architecture first.

3. AnduinOS-focused documentation

The application could prioritize information that is actually relevant to AnduinOS users instead of presenting only generic GNOME documentation.

4. Modern UI

I'm using GTK4 and Libadwaita so the application can follow the modern GNOME design approach and integrate naturally with the desktop.

5. Room for growth

I want the architecture to make it possible to add more documentation and sections later without redesigning the entire application.

Current status

The project is still under development.

I've already been experimenting with the GTK4/Libadwaita interface and the basic application structure. I'm currently focusing on getting the foundation right before adding a large amount of documentation.

I'm intentionally sharing it at this stage because I'd rather get feedback early than build a large application around assumptions that might not fit AnduinOS.

What I'd like feedback on

I'd particularly like to hear from the AnduinOS community about:

• Would an AnduinOS-specific Help application be useful?
• What documentation should it contain?
• Should it focus primarily on AnduinOS features, or also include general Linux/GNOME guidance?
• Should it eventually replace the current Help application, or complement it?
• Are there existing GNOME/AnduinOS components that I should integrate with instead of implementing separately?
• What would you consider essential for a production-ready version?

I'm also interested in feedback on the UI and overall direction.

This is currently a Show & Tell / early design discussion, so technical criticism and alternative approaches are welcome.

My main goal is to explore whether a more tightly integrated Help experience can make AnduinOS easier to understand and use while staying consistent with the GNOME ecosystem.

I'll share more of the implementation and screenshots as the prototype develops.

Thanks!

[Anduin2017]

WOW! Great! So I can finally replace the yelp.

[siyamsec-lab]

Should I improve it more or is this useful

[Anduin2017]

Both. Of course this is useful! And keep improving it!

[siyamsec-lab]

ok

[siyamsec-lab]

Question about About dialog credits/copyright:
I wrote the entire current AnduinOS Help application myself. For the About section, should I credit myself as the developer (e.g. Meheraz Hossen Siyam (@meherazhosensiam)) and keep AnduinOS Contributors for future contributions?

Also, what copyright format does AnduinOS prefer for first-party applications?
For example: © 2026 Meheraz Hossen Siyam or a project-level AnduinOS copyright notice?

[siyamsec-lab]

A quick demo of the app

[Anduin2017]

Seems somebody else is also working on a help app?

AiursoftWeb/AnduinOS-Packages#14

[siyamsec-lab]

No that is my second account

…

On Fri, 18 Sept 2026 at 19:28, Anduin Xue ***@***.***> wrote: Seems somebody else is also working on a help app? AiursoftWeb/AnduinOS-Packages#14 <AiursoftWeb/AnduinOS-Packages#14> — Reply to this email directly, view it on GitHub <#443?email_source=notifications&email_token=B4VDWAC2YRCDIILNVJHW3GT5PUZ7RA5CNFSNUABIM5UWIORPF5TWS5BNNB2WEL2ENFZWG5LTONUW63SDN5WW2ZLOOQXTCOBVGAYTEMZRUZZGKYLTN5XKMYLVORUG64VFMV3GK3TUVRTG633UMVZF6Y3MNFRWW#discussioncomment-18501231>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/B4VDWABY6SGOALCVUFGREFD5PUZ7RAVCNFSNUABIKJSXA33TNF2G64TZHM3DQMZWGA2TANJVHNCGS43DOVZXG2LPNY5TCMBYGI3TKOBVUF3AE> . Triage notifications, keep track of coding agent tasks and review pull requests on the go with GitHub Mobile for iOS <https://github.com/notifications/mobile/ios/B4VDWADURAWVIUDUI4VBDRT5PUZ7RA5CNFSNUABIM5UWIORPF5TWS5BNNB2WEL2ENFZWG5LTONUW63SDN5WW2ZLOOQXTCOBVGAYTEMZRUZZGKYLTN5XKMYLVORUG64VFMV3GK3TUVJTG633UMVZF62LPOM> and Android <https://github.com/notifications/mobile/android/B4VDWAFXEKFJFUCZ442T5QD5PUZ7RA5CNFSNUABIM5UWIORPF5TWS5BNNB2WEL2ENFZWG5LTONUW63SDN5WW2ZLOOQXTCOBVGAYTEMZRUZZGKYLTN5XKMYLVORUG64VFMV3GK3TUVZTG633UMVZF6YLOMRZG62LE>. Download it today! You are receiving this because you authored the thread.Message ID: ***@***.***>

[siyamsec-lab]

when we will see the help app on andunos

[Anduin2017]

I'm not planning to merge it since it copied all docs again which made maintaining the doc hard.

[meherazhosensiam]

OK so I will try to improve

[meherazhosensiam]

Hi @Anduin2017,

Following your feedback on my PR about duplicating the documentation, I came up with a second possible architecture.

I understand the main issue with the original PR: copying the complete documentation into anduinos-help creates another copy that would need to be maintained.

Instead of maintaining a second documentation tree, I'm considering modifying the existing Help application architecture/UI itself and keeping the documentation as a separate source of truth.

The idea would be:

                 AnduinOS Help
                       │
          ┌────────────┴────────────┐
          │                         │
     Native Help UI           Documentation
     + AnduinOS UI            remains external
     + AnduinOS SVG/logo            │
     + navigation                   │
     + search/routing               ▼
     + app functionality     Official AnduinOS Docs

The application would therefore be responsible for the Help experience and UI, but it would not contain a duplicated copy of all the documentation.

This would allow us to customize the application for AnduinOS while keeping the documentation maintained in one place.

For the implementation, I'm considering using the existing upstream Help application/source as the technical foundation where appropriate, while:

• preserving upstream licensing and attribution;
• replacing upstream branding with AnduinOS branding;
• using AnduinOS SVG/assets;
• adapting the UI to fit AnduinOS;
• routing documentation topics to the official AnduinOS documentation;
• avoiding a second copy of the complete documentation;
• keeping AnduinOS-specific application functionality separate from the documentation itself.

I haven't started this alternative implementation because I wanted to check whether this architecture would be acceptable before making another substantial change.

If you prefer the original lightweight approach, I'm also happy to keep the current PR focused on removing the duplicated documentation.

[Anduin2017]

I'm still considering that. I prefer a native app. If this app is just a website wrapper, it't not worthy to make it looks like an app.

By the way, you can check the source code of: https://github.com/aiursoftweb/docsviewer

That runs a background job to fetch latest doc and index it to a local db.

[siyamsec-lab]

OK so we need to design a application that will fetch the documentation from the website So we don't need to Separately modify Each one we have to only modify one docs

[siyamsec-lab]

Following up on your anduinos-help review notes, I’ve completed a substantial refactor based on your DocsViewer suggestion. The application is now a native GTK 4 + Libadwaita documentation client rather than a thin browser wrapper: there is no WebKit dependency, and normal navigation no longer launches external browser tabs. What was wrong with the previous implementation The previous iteration routed sidebar navigation and search directly to https://docs.anduinos.com/ in the user’s default browser. This made the application feel more like a launcher than a native Help Center. There were also two routing issues: - Category links used paths such as /Install/, while the documentation site uses routes such as /Documents/Index?category=Install. - Search used ?q= instead of the actual /Documents/Search?q= route. As a result, some navigation produced 404s and the application did not provide an offline documentation experience. What has been implemented Following the Aiursoft.DocsViewer approach, particularly the SyncDocsRepoJob + IndexDocumentsJob pattern, the Help Center now works from a local clone and SQLite index. Documentation synchronization - Clones https://github.com/AiursoftWeb/AnduinOS-Docs.git on first launch using a shallow --depth 1 clone. - Stores the repository under: ~/.local/share/anduinos-help/docs-repo/repo/ - On subsequent launches, synchronizes only when the previous sync is more than six hours old. - Parses properdocs.yml to obtain the canonical documentation navigation tree. - Uses the same navigation source as DocsViewer, keeping the application’s hierarchy aligned with the documentation site. SQLite document store All Markdown files under Docs/ are indexed into: ~/.local/share/anduinos-help/docs.db Each document stores: - title - category - content - file_last_modified - source URL - source repository URL - soft-delete state The navigation tree is also persisted in SQLite, so the sidebar does not need to reparse YAML on every launch. Fully native offline rendering After synchronization, documentation is available without network access. Markdown is parsed with markdown-it-py into an intermediate representation and rendered using native GTK widgets rather than a WebView. The renderer currently supports: - headings - paragraphs - code blocks - copy-to-clipboard controls - language badges - root-prompt detection - note/tip/warning/danger callouts - tables - ordered and unordered lists - blockquotes - horizontal rules Full-text search Search has been moved to SQLite FTS5. It uses the porter + unicode61 tokenizer and searches both titles and document content. Results are ranked using BM25 and include highlighted snippets. Multi-term queries are supported; for example: usb stick can match content such as “Burn a USB Stick”. The existing command-extraction search has also been retained for the *Matching terminal commands* section. Native navigation The sidebar is now generated from the persisted properdocs.yml navigation tree. The current live documentation structure contains: - Home - Install — 41 articles - Skills — 28 - Applications — 117 - Apkg — 16 - Servicing — 21 - Virtualization — 4 Category counts are displayed as badges. Selecting a category opens a native category listing, while selecting an article opens the native article renderer. The application also now provides: - Back / Forward - Home - Refresh - Navigation history - Ctrl+H - Ctrl+R / F5 - Ctrl+F / Ctrl+K for search - Ctrl+G for glossary - Ctrl+Shift+D for diagnostics - Ctrl+Shift+B for reporting a problem - F11 for fullscreen - Ctrl+? for keyboard shortcuts Documentation refresh The new win.refresh-docs flow opens a native refresh dialog showing: - last synchronization time - indexed document count - a *Refresh now* action The synchronization and re-indexing run in a worker thread, with progress reported to the UI. Once synchronization finishes, the sidebar is repopulated automatically. Removed components The previous flat-file documentation stack has been removed: - loader.py - index.json - bundled articles/*.md - parser.py - search.py - cache.py - updater.py - scripts/sync_docs.py - bundled assets/articles/ - assets/index.json - assets/meta.json - assets/sync-report.json - generated obj/ and bin/ directories - the previous WebView implementation (ui/webview.py, online.py) docs/sync.py now replaces the old synchronization script, and SQLite replaces the bundled Markdown/index architecture. Dependency changes Dependency Change Reason python3-markdown-it Kept Markdown → IR parsing python3-rapidfuzz Removed SQLite FTS5 replaces fuzzy matching python3-requests Removed Git CLI handles repository synchronization python3-yaml Kept Parses properdocs.yml gir1.2-webkit-6.0 Removed No WebView is required git Added Repository clone/pullVerification I also ran the implementation through an end-to-end test using a freshly extracted build. Results: - *235 documents* indexed from the live AiursoftWeb/AnduinOS-Docs repository - Initial indexing completed in approximately *5.2 seconds* - *7 categories* discovered automatically from properdocs.yml - Article lookup verified with install/download-anduinos - Correctly resolves to *Download Anduinos* - Category and subcategory metadata are preserved - 14 Markdown blocks were parsed for the test article - FTS5 search verified with apt - Search returned ranked results with snippets - *35/35 tests passed* - 10 test_store.py - 7 test_parser.py - 7 test_links.py - 5 test_version.py - 6 test_diagnostics.py - All *33 Python files* pass AST parsing - No dangling imports of the removed modules were detected Preserved functionality The refactor does not remove the existing system-oriented features that do not depend on local documentation: - System Diagnostics - Copy-to-clipboard diagnostic reports - Report a Problem - pre-filled issue templates with system information - Glossary - About - Keyboard Shortcuts The URL security boundary in utils/links.py is also preserved. External destinations such as GitHub, the issue tracker, and the AnduinOS homepage continue to open through the allow-listed open_external helper. Arbitrary URL schemes are not passed directly to the system browser. The i18n workflow is also intact. po/anduinos-help.pot, po/en_US.po, and po/zh_CN.po have been regenerated, and compile-locales.sh remains the configured PrebuildCommand. Current project structure src/anduinos_help/ ├── main.py ├── docs/ │ ├── store.py │ ├── sync.py │ ├── nav.py │ ├── parser.py │ ├── loader.py │ └── search.py ├── ui/ │ ├── window.py │ ├── sidebar.py │ ├── home.py │ ├── article_view.py │ ├── category.py │ ├── search.py │ ├── code_block.py │ ├── dialogs.py │ └── widgets.py ├── utils/ │ ├── paths.py │ ├── links.py │ └── logging.py └── system/ ├── version.py └── diagnostics.py The only documentation-related asset shipped with the package is assets/style.css. Markdown documentation is no longer bundled into the .deb. Runtime data is stored under: ~/.local/share/anduinos-help/ ~/.local/state/anduinos-help/ Deliverable The updated source package is: anduinos-help-package.zip - 87 KB - 43 files The generated runtime database, cloned documentation repository, and logs are intentionally created at runtime rather than shipped with the package. Next steps The implementation is ready for packaging and real-desktop validation. apkg lint apkg test --profile anduinos-package-release-test apkg build --all The resulting .deb should then be installed on a real AnduinOS desktop and tested for: 1. First-launch repository synchronization 2. Sidebar population 3. Native Markdown rendering 4. Search and FTS5 ranking 5. Offline article access 6. Refresh/re-index behavior 7. GTK/Libadwaita visual consistency 8. Error handling when the documentation repository is unavailable The initial sync currently runs on startup and on demand. If periodic synchronization is preferred, the next incremental change would be to add a GLib.timeout_add_seconds() timer in main.py for a six-hour refresh interval.

…

On Tue, 22 Sept 2026 at 19:50, Anduin Xue ***@***.***> wrote: I'm still considering that. I prefer a native app. If this app is just a website wrapper, it't not worthy to make it looks like an app. By the way, you can check the source code of: https://github.com/aiursoftweb/docsviewer That runs a background job to fetch latest doc and index it to a local db. — Reply to this email directly, view it on GitHub <#443?email_source=notifications&email_token=B4VDWADUC36FZ4DVQ7TKUU35QJ7S3A5CNFSNUABIM5UWIORPF5TWS5BNNB2WEL2ENFZWG5LTONUW63SDN5WW2ZLOOQXTCOBVGUZTONJZUZZGKYLTN5XKMYLVORUG64VFMV3GK3TUVRTG633UMVZF6Y3MNFRWW#discussioncomment-18553759>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/B4VDWABGVURVGOLFTNMFP635QJ7S3AVCNFSNUABIKJSXA33TNF2G64TZHM3DQMZWGA2TANJVHNCGS43DOVZXG2LPNY5TCMBYGI3TKOBVUF3AE> . Triage notifications, keep track of coding agent tasks and review pull requests on the go with GitHub Mobile for iOS <https://github.com/notifications/mobile/ios/B4VDWAEXNMOTCHODO7Q2OBT5QJ7S3A5CNFSNUABIM5UWIORPF5TWS5BNNB2WEL2ENFZWG5LTONUW63SDN5WW2ZLOOQXTCOBVGUZTONJZUZZGKYLTN5XKMYLVORUG64VFMV3GK3TUVJTG633UMVZF62LPOM> and Android <https://github.com/notifications/mobile/android/B4VDWAGDQ2ENYSGXSQ4GFCD5QJ7S3A5CNFSNUABIM5UWIORPF5TWS5BNNB2WEL2ENFZWG5LTONUW63SDN5WW2ZLOOQXTCOBVGUZTONJZUZZGKYLTN5XKMYLVORUG64VFMV3GK3TUVZTG633UMVZF6YLOMRZG62LE>. Download it today! You are receiving this because you authored the thread.Message ID: ***@***.***>

[Anduin2017]

Wow awesome! Link to the PR? I will have a try soon!

[siyamsec-lab]

i wil pull it soon

[siyamsec-lab]

this the PR AiursoftWeb/AnduinOS-Packages#14