Skip to content

Refresh the docs homepage, code blocks, admonitions and screenshots - #78

Open
gams87 wants to merge 4 commits into
mainfrom
docs-home-redesign
Open

gams87 wants to merge 4 commits into
mainfrom
docs-home-redesign

Conversation

@gams87

@gams87 gams87 commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Summary

A proposal for a new docs homepage. The current one leads with the company mission and a sales banner, and its three cards use clipart icons in mixed styles. Most visitors come to search or to find a specific topic, so the new page puts that first:

  • Hero with a large search box. It opens the same search modal as the navbar (Cmd/Ctrl+K), plus Get started and Tutorials buttons.
  • Start here by role. Administrators and developers each get a card with direct links into Getting Started.
  • Browse by topic. Eight cards (Airflow, dbt, VS Code, Snowflake, Git, Security and secrets, Metrics and logs, Administration), each with links to the most used pages.
  • Consistent line icons (Lucide, ISC license) inlined in the brand blue, with no new dependency.
  • How-tos, Best practices and Reference kept as a compact row.
  • The sales section reduced to a one-line "Book a demo" band.
  • Works in light and dark mode and on small screens.

The old HomepageFeatures and CTA components and their three SVGs are removed; nothing else used them.

Code blocks

  • Bash, SQL and Jinja are highlighted. Docusaurus only bundles a few Prism languages, so the 39 bash and 24 sql blocks rendered as plain text. They are now loaded through additionalLanguages, with django for the dbt Jinja blocks (fenced as jinja2) and ini for the .env snippets.
  • New themes: One Light and One Dark (were GitHub and Dracula), a matching pair that sits better with the navy and blue palette.
  • Lighter styling: a thin border instead of the drop shadow, slightly smaller type, a quieter title bar, and a matching border on inline code.
  • Six fences renamed so they match a Prism language (jinja to jinja2, JSON to json, env to ini).

Admonitions and screenshots

  • Admonitions (note, tip, info, warning, caution) get a light tint, a colored left edge and a colored title, with the regular text color for the body. In dark mode this replaces Infima's flat gray note and heavy brown warning.
  • Screenshots inside the docs get a thin frame and rounded corners, and in dark mode are dimmed slightly with a soft shadow so white product captures don't glare.

About 235 blocks still declare no language and render as plain text; adding it is content cleanup for a follow-up.

Screenshots

Before

home-light

After (light)

new-light

After (dark)

new-dark

After (mobile)

new-mobile

Code blocks

Before After
Bash before-bash-light after-bash-light
SQL before-sql-light after-sql-light
YAML before-yaml-light after-yaml-light
Python (dark) before-python-dark after-python-dark

Admonitions (light and dark)

Before After
admonitions-before admonitions-after

Screenshot in dark mode

Before After
image-dark-before image-dark-after

Checklist

  • [Mandatory] My pull request represents one logical piece of work and my commits are related and look clean.

🤖 Generated with Claude Code

https://claude.ai/code/session_015pcV34KcZ9UzUQGmj35oJJ

@gams87
gams87 requested a review from noel November 13, 2026 22:03
@gams87
gams87 marked this pull request as draft November 13, 2026 22:08
@gams87 gams87 changed the title Redesign the docs homepage around search, roles and topics Redesign the docs homepage and code blocks Nov 13, 2026
gams87 and others added 2 commits November 13, 2026 16:13
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015pcV34KcZ9UzUQGmj35oJJ
@gams87 gams87 changed the title Redesign the docs homepage and code blocks Refresh the docs homepage, code blocks, admonitions and screenshots Nov 13, 2026
@gams87
gams87 marked this pull request as ready for review November 13, 2026 22:30

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants