Skip to content

Add Technological Foundations documentation page - #5835

Merged
falkoschindler merged 6 commits into
zauberzeug:mainfrom
evnchn:technological-foundations
Apr 1, 2026
Merged

Add Technological Foundations documentation page#5835
falkoschindler merged 6 commits into
zauberzeug:mainfrom
evnchn:technological-foundations

Conversation

@evnchn

@evnchn evnchn commented Feb 22, 2026

Copy link
Copy Markdown
Collaborator

Motivation

The homepage Features section currently links out to external websites for core technologies (vuejs.org, quasar.dev, fastapi.tiangolo.com, tailwindcss.com). This is an SEO problem: outbound links on high-traffic pages bleed PageRank to third-party domains instead of keeping visitors within the NiceGUI documentation. Search engines also favor sites with strong internal linking over those that immediately send users elsewhere.

Additionally, NiceGUI's technology stack explanations are currently scattered across markdown files that most users never see:

None of this information is on the documentation website itself. This PR creates a proper, user-facing documentation page that explains the technology choices and how they fit together.

Implementation

New section_foundations.py documentation page — "Technological Foundations" with six sections, each using @doc.part() with side-by-side grid layout (2fr text / 1fr visual):

Section Text content Visual
UI Framework Vue.js role, JustPy inspiration, custom Vue components, alpha-level other-framework support Mermaid diagram: NiceGUI Element → Vue Component → Browser DOM
Component Library Quasar's 70+ components, __init__ params vs .props(), occasional renames NiceGUI-to-Quasar element mapping table with .props() examples
Backend FastAPI/Starlette/Uvicorn stack, REST mixing, ui.run_with(), ASGI mounting Mermaid diagram: NiceGUI + Other Routes → FastAPI → Uvicorn ← Other ASGI Apps
Real-Time Communication Socket.IO transports, fallback, reconnection, rooms; Outbox batching, message IDs, rewind/replay, ack pruning Mermaid diagram: NiceGUI → Outbox → Socket.IO → Browser with feedback loops
Styling Tailwind CSS (CDN, most features), UnoCSS (lighter, mini preset), Quasar CSS (built-in, lightest) Progress bar comparison: Features vs Lightweight for each engine
How It All Fits Together Summary tying all pieces together

Homepage link updates:

  • Features section links (Vue, Quasar, FastAPI, Tailwind CSS) now point to the corresponding foundations sections instead of external websites
  • "Python 3.10+" replaced with "real-time sync via Socket.IO" (links to foundations)

Documentation overview: added import and tile for the new section.

Progress

  • I chose a meaningful title that completes the sentence: "If applied, this PR will..."
  • The implementation is complete.
  • If this PR addresses a security issue, it has been coordinated via the security advisory process.
  • Pytests have been added (or are not necessary).
  • Documentation has been added (or is not necessary).

Note: This PR depends on #5813 (SEO support) being merged first, as both PRs modify website/main_page.py and the SEO improvements provide the foundation for the discoverability goals here.

@evnchn evnchn added the documentation Type/scope: Documentation, examples and website label Feb 22, 2026
@evnchn

evnchn commented Feb 22, 2026

Copy link
Copy Markdown
Collaborator Author
foundations-full-page

@falkoschindler falkoschindler added the review Status: PR is open and needs review label Feb 23, 2026
@falkoschindler falkoschindler added this to the 3.10 milestone Feb 23, 2026
@evnchn

evnchn commented Mar 29, 2026

Copy link
Copy Markdown
Collaborator Author

Two things:

  1. Merge conflicts, of course.
  2. Actually outgoing links in main page is fine SEO-sense.

If you'd trust Claude:

Outgoing links carry less SEO weight than you might fear. Google has long understood that linking out to authoritative sources (Vue, Tailwind, FastAPI, etc.) is a signal of quality and context, not a penalty. A NiceGUI intro page that says "built on Vue.js, Tailwind CSS, and FastAPI" with outgoing links to each is totally fine.

Then I'd say "learn more -> tech foundations page" then. The page is still useful for more tech-minded people and contributors to get a sense of NiceGUI internals. Also brings AI agents up to speed.

Add a new documentation page explaining NiceGUI's technology stack:
Vue.js, Quasar, FastAPI, Socket.IO, and CSS engines. Each section
includes explanatory text with diagrams or visual aids.

Add a "learn more" link in the features section pointing to the new
page, keeping external links to upstream projects intact.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@evnchn
evnchn force-pushed the technological-foundations branch from 76e2a48 to 974f1a6 Compare March 29, 2026 19:18
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@evnchn

evnchn commented Mar 29, 2026

Copy link
Copy Markdown
Collaborator Author

@falkoschindler Now it's purely an addition then, similar to security best practices. Should be less controversial to review as well.

falkoschindler and others added 4 commits April 1, 2026 13:59

@falkoschindler falkoschindler left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, @evnchn!
After some minor improvements here and there the PR is ready to merge. 🚀

@falkoschindler
falkoschindler enabled auto-merge April 1, 2026 12:59
@falkoschindler
falkoschindler added this pull request to the merge queue Apr 1, 2026
Merged via the queue into zauberzeug:main with commit a556af2 Apr 1, 2026
7 checks passed
@evnchn
evnchn deleted the technological-foundations branch April 1, 2026 15:39
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Type/scope: Documentation, examples and website review Status: PR is open and needs review

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants