brimdata / zed-docs-site

The Zed Docs Website

This repository contains Docusaurus 2 source and configuration files for generating the static website for the public documentation of the open-source Zed project.

All content for the documentation is stored in markdown files in the docs directory of the Zed repository.

Setup

To setup the Docusaurus environment, clone this repo, cd into it, and run:

$ yarn

Local Development

To edit or author new documentation, it's easiest to clone the zed repository into the same top-level directory as this repo and simply run make dev in this repo. This will create a symlink from called docs in this directory that points to ../zed/docs, launches the local docusaurus server, and directs your browser to this server.

You can ctrl-C the make dev process to stop the server.

Any edits you make to files in ../zed/docs will be immediatedly re-rendered by the docusaurus server.

Rendering from zed repo

If you don't have a clone of the zed repo in .., you can pull the zed repo docs directory into the ./docs subdirectory by running:

make fetch-latest

Then you can run the docusaurus server with:

$ yarn start

This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.

Build

$ yarn build

This command generates static content into the build directory and can be served using any static contents hosting service.

zed-docs-site's Issues

Add a link checker

I recently realized the deployed docs site could benefit from an automated link checker, since this would find issues like #26, i.e., links that are fine when browsing the docs within GitHub but then break after being deployed to https://zed.brimdata.io/.

I've started running some tests using the same ruzickap/action-my-broken-link-checker that's currently used on the brimdata.io web site. In addition to flagging the #26 errors, it also uncovered new issues #27 and the broken links being fixed in brimdata/zed#4028.

Once we've got those and any other issues addressed such that the link checker passes cleanly on the deployed site, I'll add that Action to the Workflows in this repo so it always runs and notifies us of new breakages as they occur.

Search not working

It was reported that the Search feature on the docs site is not working. When trying to reproduce, I stumbled onto the fact that selecting a different Zed version in the drop-down somehow seems to wake it up and start working. However, if I start fresh in a new Incognito window, I can always reproduce it failing again.

See the attached video for an example.

Repro.mp4

Links to sample data cause a 404

A community user reported the following via private gist.

There's links to sample data from the docs that currently result in a 404. For instance, the one linked from the section https://zed.brimdata.io/docs/next/tutorials/zed/#adding-data-to-our-lake highlighted here:

When clicked:

It doesn't fail when clicked in the page's original location within section https://github.com/brimdata/zed/blob/main/docs/tutorials/zed.md#adding-data-to-our-lake on GitHub, however. The original markdown link is just [here](github1.zng), and when clicked from within GitHub that resolves to https://github.com/brimdata/zed/blob/main/docs/tutorials/github1.zng. For what it's worth, that may not be a great link destination either, because it just brings the user to a page at https://github.com/brimdata/zed/blob/main/docs/tutorials/github1.zng that looks like this:

At this point clicking either "View Raw" or that "Download" button both end up downloading the file. So having this link resolve to the intermediate screen doesn't seem to be helping the user much.

Meanwhile, on the deployed docs website, the hyperlink that 404s ends up as https://zed.brimdata.io/assets/files/github1-2496d524ce44f4cb9f32cfeb70fa669e.zng/. Based on what I see in the Docusaurus docs, I guess it recognizes it's a file destination and downloads it and serves it out of this assets/ directory. In any case, as it turns out, if we just remove the trailing slash, the link works fine as https://zed.brimdata.io/assets/files/github1-2496d524ce44f4cb9f32cfeb70fa669e.zng.

Therefore, I can see see at least two possible ways out, though I'm sure there's others:

1. We could change the destination for the link in the original markdown to be https://github.com/brimdata/zed/raw/main/docs/tutorials/github1.zng (i.e., the link attached to that "Download" button), since it looks like that link would stay as-is even after Docusaurus publishes the site. This would have the added bonus that if users ever click the link in the original page on GitHub it'll go straight to download, but maybe there's other negatives to having an absolute URL like that.

2. Someone could figure out how to remove the trailing slash from the generated link on the docs site or figure out how to make our web site serve a file destination even if it has a trailing slash. FWIW, I did some searching and found people at facebook/docusaurus#6282 talking about a similar problem.

HTTP 404 when clicking "Edit this page" link on versioned docs

As shown in the attached video, the "Edit this page" link that appears at the bottom of pages in the docs site can produce a 404 error.

Repro.mp4

I've observed that this happens for any of the "versioned" docs (i.e., having selected v1.2.0 or v1.1.0 in the pull-down in the top menu bar), though if one happens to have version Next selected, it does successfully link to the relevant URL in the original GitHub repo. However, if a user coming "fresh" to the docs site (such as in the Incognito window shown here) they land immediately in the most recent version, so this broken link is hazardous. It's also foiling the link checker automation I'm trying to point at the docs site. 😉

I'm doubtful that this "Edit this page" feature is going to be used much, so I'd be ok with the quick fix of just removing it.