feat: added initial rework of docs #148

0xcadams · 2025-07-09T18:14:47Z

Updated docs with:

Revamped search using cmdk and lazy imports instead of a fetch to pull the JSON. Reduced the debounce time and added preloading so it feels fast. Fixed markdown to plaintext.
Reworked navigation: renamed sections for (hopefully) more clarity, added icons & animations, changed grouping, and made some groups default to closed to feel less overwhelming.
Random rewording for clarity.
Added fun hotkeys for quick navigation around the docs.

vercel · 2025-07-09T18:14:54Z

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
zero-docs	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Jul 10, 2025 6:35pm

0xcadams · 2025-07-09T21:08:08Z

@aboodman @alexhking welcome any feedback you have here (I can't assign you as reviewers yet w/o permissions).

aboodman · 2025-07-10T09:58:07Z

Wow!

Supportive of most of this. Specific feedback:

I do not like the visual noise of the hotkeys on the buttons and links. Sorry.
I do not like to use rules (lines) as separators in our designs if we can avoid it. I like the layouts to be clean enough to not need them. I do not think they are needed here. Remove.
I like the improved performance of the search.
I do not like how the search box changes size depending on how many results there are. It should always be the same size.
I am mixed on the icons, but I want to try it out for a bit.
I like the restructure of the nav, but I think that "Postgres" should continue being the second section
There is a layout bug introduced around the subnav
on the right side where it doesn't always align w/ the search box (see video: https://github.com/user-attachments/assets/82f980df-d102-4199-9db7-8cfa16b837fe)
"markdown to text" – nice fix.
I need to go through the copy changes.

alexhking · 2025-07-10T14:51:52Z

Nice! This is a whole lot of work and looks pretty cool. I did notice a few things looking through the code and while testing it out. Going to do a deep dive and then do inline comments, etc. Thanks!

0xcadams · 2025-07-10T15:37:46Z

Sounds great - I will make updates based on this (and Alex I'll wait for your feedback). If either of you have any changes for how the icons are shown, let me know. I was trying to make the sections clearer visually.

I will make smaller PRs in the future, got a bit ahead of myself.

alexhking · 2025-07-10T17:10:43Z

initial-review-compressed.mp4

@0xcadams ☝🏼 Initial visual review

alexhking

Added some inline comments along with the video from above. Thanks for the nice work!

alexhking · 2025-07-10T17:12:30Z

app/page.tsx

@@ -57,21 +72,26 @@ export default function Home() {

        <div className={styles.navLinks}>
          <Button
-            variant="outline"
-            className={styles.primaryButton}
+            className="flex items-center gap-2"


I notice that you're putting back the tailwind classes. Initially when we created this docs site from Aria Docs, we wanted to get rid of tailwind completely. I'm not a huge fan of it, but if you're more comfortable using it we can keep it.

Got it - I was under the impression you were trying to move in the opposite direction. Yeah personally I like tailwind because it is simple and global styles are tough to manage as things grow. But duly noted, I won't step on these changes in the future

alexhking · 2025-07-10T17:18:56Z

components/search.tsx

+                    <CommandItem
+                      key={item.id}
+                      value={item.id}
+                      onSelect={() => {


This is where things could break with standard browser behavior. Handling navigation with router.push breaks standard link functionality.

Yeah, fair point. I will try to rework to use links with prevent default. Not sure how well that integrates with cmdk

app/globals.css

components/Pagination.tsx

components/search.tsx

alexhking · 2025-07-10T17:39:07Z

components/toc.tsx

+    [tocs, level2Tocs],
+  );
+
+  useHotkeys(['0', '1', '2', '3', '4', '5', '6', '7', '8', '9'], e => {


What do we do if more than 10 headings exist?

The hotkeys only apply to the first ten - and if there's only one header it doesn't show them.

components/toc.tsx

0xcadams · 2025-07-10T18:36:55Z

Thanks for the feedback!

I made some changes to the search box - pinned to the top. It's more similar to how it currently is - let me know if this doesn't address feedback.

I do not like the visual noise of the hotkeys on the buttons and links. Sorry.

I moved this to a tooltip instead of showing in the button. Agreed it was noisy.

I do not like to use rules (lines) as separators in our designs if we can avoid it. I like the layouts to be clean enough to not need them. I do not think they are needed here. Remove.

Removed

I am mixed on the icons, but I want to try it out for a bit.

Open to any changes here

I like the restructure of the nav, but I think that "Postgres" should continue being the second section

Done

There is a layout bug introduced around the subnav
on the right side where it doesn't always align w/ the search box (see video: https://github.com/user-attachments/assets/82f980df-d102-4199-9db7-8cfa16b837fe)

Fixed this

I need to go through the copy changes.

Should've done these separately, will do this in the future.

Alex:

I changed the icon for the solidjs - let me know if this is better. The icons are mostly based on Lucide (shadcn and a lot of projects use it): https://lucide.dev/icons. Exceptions are the brand logos (React and SolidJS)
I fixed the back button issue - thanks for finding that.

alexhking · 2025-07-11T20:42:54Z

Thanks for the quick revisions. On the surface it looks good to me, the hover states are cool. Curious what @aboodman thinks. Otherwise, lgtm.

aboodman · 2025-07-12T10:36:12Z

Few more bits of visual feedback in attached movie: CleanShot 2025-07-12 at 00.23.31.mp4 <https://drive.google.com/file/d/18jRcLQwQ-NR6yX_fQ8qIsTvpDGXSYvJK/view?usp=drive_web> As for tooltips, sorry still not a fan, it just seems superfluous. How often is somebody going to click on these? Are shortcuts really needed? It seems harder to process that there is a shortcut and use it than to just click? Is this something you yourself want Chase? Or thinking others wants it?

…

On Fri, Jul 11, 2025 at 10:43 AM Alexander King ***@***.***> wrote: *alexhking* left a comment (rocicorp/zero-docs#148) <#148 (comment)> Thanks for the quick revisions. On the surface it looks good to me, the hover states are cool. Curious what @aboodman <https://github.com/aboodman> thinks. Otherwise, lgtm. — Reply to this email directly, view it on GitHub <#148 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAATUBGBO2CRID3WDQA4BED3IAOWJAVCNFSM6AAAAACBE3HVZGVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTANRTG43DEOBSGM> . You are receiving this because you were mentioned.Message ID: ***@***.***>

0xcadams · 2025-07-12T13:52:13Z

Few more bits of visual feedback in attached movie:

I will address these!

As for tooltips, sorry still not a fan, it just seems superfluous. How often is somebody going to click on these? Are shortcuts really needed? It seems harder to process that there is a shortcut and use it than to just click? Is this something you yourself want Chase? Or thinking others wants it?

My thought process was that it's more of a branding choice.

I assume a lot of early adopters using Zero (and early inspirational products using sync engines) have keyboard shortcuts. To my mind, it's more of a reflection of how zero users want their products to be - fast to load, fast to search, and have keyboard shortcuts for fast navigation.

That being said, they're not incredibly useful and personally I would likely not use them outside of the novelty of it. I'm open to feedback - up to you where you want this to go!

aboodman · 2025-07-12T20:26:02Z

I assume a lot of early adopters using Zero (and early inspirational products using sync engines) have keyboard shortcuts. To my mind, it's more of a reflection of how zero users want their products to be - fast to load, fast to search, and have keyboard shortcuts for fast navigation.

Ah! That's an interesting rationale. But yeah I think let's not do things artificially. The docs are a reflection of our quality standards too and part of quality is making things useful (and only making things that are useful).

Anyway, we have zbugs which is an actual real app that we can use and add keyboard shortcuts to.

aboodman · 2025-07-12T20:26:45Z

A trick I often use with product questions is just asking what we ourselves want. We are the target market for Zero.

feat: added initial rework of docs

df731d1

vercel bot had a problem deploying to Preview July 9, 2025 18:15 Failure

0xcadams added 2 commits July 9, 2025 11:17

fix: formatting

60fcd0a

chore: lint

6de3fbd

vercel bot deployed to Preview July 9, 2025 18:18 View deployment

vercel bot deployed to Preview July 9, 2025 18:19 View deployment

fix: added fixes for styling

89659e9

vercel bot deployed to Preview July 9, 2025 19:38 View deployment

fix: fixes from testing

092140f

vercel bot deployed to Preview July 9, 2025 19:55 View deployment

fix: fixes from testing

21ba9a5

vercel bot deployed to Preview July 9, 2025 20:10 View deployment

fix: make cmdk loop

e760e05

vercel bot deployed to Preview July 9, 2025 20:15 View deployment

fix: added prefetching

7e05721

vercel bot had a problem deploying to Preview July 9, 2025 20:36 Failure

fix: types

6f0e856

vercel bot deployed to Preview July 9, 2025 20:38 View deployment

fix: revert rename

7f869ba

vercel bot had a problem deploying to Preview July 9, 2025 20:51 Failure

0xcadams marked this pull request as ready for review July 9, 2025 20:55

fix: routes config

629bf06

vercel bot deployed to Preview July 9, 2025 20:56 View deployment

fix: missing css

40a4f1f

vercel bot deployed to Preview July 9, 2025 22:37 View deployment

feat: added further hotkeys

9461b6e

vercel bot deployed to Preview July 9, 2025 23:39 View deployment

alexhking self-requested a review July 10, 2025 14:52

alexhking reviewed Jul 10, 2025

View reviewed changes

fix: added fixes based on feedback

a1dd6d3

vercel bot deployed to Preview July 10, 2025 18:11 View deployment

fix: added link to cmd item

422e134

vercel bot deployed to Preview July 10, 2025 18:35 View deployment

feat: added initial rework of docs #148

Are you sure you want to change the base?

feat: added initial rework of docs #148

Conversation

0xcadams commented Jul 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vercel bot commented Jul 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

0xcadams commented Jul 9, 2025

Uh oh!

aboodman commented Jul 10, 2025

Uh oh!

alexhking commented Jul 10, 2025

Uh oh!

0xcadams commented Jul 10, 2025

Uh oh!

alexhking commented Jul 10, 2025

Uh oh!

alexhking left a comment

Choose a reason for hiding this comment

Uh oh!

alexhking Jul 10, 2025

Choose a reason for hiding this comment

Uh oh!

0xcadams Jul 10, 2025

Choose a reason for hiding this comment

Uh oh!

alexhking Jul 10, 2025

Choose a reason for hiding this comment

Uh oh!

0xcadams Jul 10, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

alexhking Jul 10, 2025

Choose a reason for hiding this comment

Uh oh!

0xcadams Jul 10, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

0xcadams commented Jul 10, 2025

Uh oh!

alexhking commented Jul 11, 2025

Uh oh!

aboodman commented Jul 12, 2025 via email

Uh oh!

0xcadams commented Jul 12, 2025

Uh oh!

aboodman commented Jul 12, 2025

Uh oh!

aboodman commented Jul 12, 2025

Uh oh!

Uh oh!

0xcadams commented Jul 9, 2025 •

edited

Loading

vercel bot commented Jul 9, 2025 •

edited

Loading