feat(website): new documentation

[shortcuts]

Summary

This PR documents the new DocSearch infrastructure, the DocSearch v3 component and finalizes the migration from the previous website repository to this one.

Preview

You can see the live deploy with an up-to-date search.

Changes

legacy documentation

All of the actual documentation (minus references of the previous infra) is still available.

current documentation

• Parts of the previously written documentation (what is DocSearch, goals, requirements, tips, etc.)
• DocSearch v3
  • JS and React packages usage and API reference
  • CSS package (files only for now)
• Crawler
  • helpers.docsearch extractor method, API and a few examples
  • Config templates for website generators
  • Other Crawler parts are documented on the Algolia documentation
• Migration page with differences from legacy to current

Apply page

Due to many applications sent without reading the checklist (commercial usage for example), I thought having a checkbox for each requirements would be better.

README

READMEs have been updated with the new documentation links and a similar format to what we've done in Autocomplete

TODO

• Fix Tailwindcss and Docusaurus styling conflict (Tailwind overrides the default Docusaurus styles)
• Re-proofreading
• Change Netlify deploy target

How to test

• yarn && yarn website:start

When to merge

We will wait for the migration to officially start before publishing the new documentation

[codesandbox-ci]

This pull request is automatically built and testable in CodeSandbox.

To see build info of the built libraries, click here or the icon next to each commit SHA.

Latest deployment of this branch, based on commit 3a0ec24:

Sandbox	Source
Vanilla	Configuration

[bodinsamuel]

Did a very quick first pass on the first files.
This is very good, love it 😍❤️

• Can not click "give it a star" banner at top (neither click or close)
• On a 13" the homescreen is bit too big, I barely see the numbers, I would reduce a bit the up/down margin.

[bodinsamuel]

I would emphasis that all of them are accesible in the Crawler UI
And also that they are Crawler config.

A screenshot can help

[shortcuts]

Can not click "give it a star" banner at top (neither click or close)

Indeed, there's also the stat banner and apply form that have a white background in dark mode after a hard refresh, but all of them work in dev. I'll check!

[Shipow]

I love it! Let's go team!

[francoischalifour]

I've reviewed until "how-does-it-work.mdx" — great so far!

Would be nice to re-structure the sidebar sections as a follow-up PR, I have a hard time with the order and flow.

[francoischalifour]

Nice work!

Maybe we can capitalize the versions in the dropdown? It's the only text that's not.

[shortcuts]

Maybe we can capitalize the versions in the dropdown? It's the only text that's not.

I wanted to but didn't found a way to do it for the dropdown only, which means capitalizing it for the whole website and doesn't seem right in some places

[bodinsamuel]

I wanted to but didn't found a way to do it for the dropdown only,

select > option { text-transform: capitalize } 😬

[bodinsamuel]

Massive 🏋🏻

I have made a few suggestions, I'm not technical writer so feel free to discard it's just my own feeling.

[bodinsamuel]

This might be good to document it in our main Doc too, as we are now exposing it to everyone

[bodinsamuel]

This page seems really similar to the end of packages/website/docs/required-configuration.mdx maybe you could gather the content

[sarahdayan]

Great work @shortcuts! Here's a first pass of comments based on the visual aspect of the site. I'll do a second review of the code later on if you need to, although you probably already received a fair share of comments so let me know if this is needed or not.

I didn't check the previous reviews so feel free to disregard points if they have been discussed already.

Dark mode

The dark mode doesn't look as nice as the default light mode. The site looks "inverted", the contrast is either too low (text vs. background) or too strong (dark zones vs. light zones), and there are some readability issues.

The text is hard to read, and some logos don't play well with the dark background. Maybe silhouette logos would work better?

The header doesn't distinguish for the hero background, which makes the hero pattern look "cut".

My eye is drawn to that top banner.

Weird issue where toggling between dark and light mode doesn't seem deterministic.

Enregistrement.de.l.ecran.2021-09-27.a.13.18.50.mov

Illustrations and icons

Some of the SVG illustrations use text with some ugly default serif font. I suspect this is because the text layer is still a text object. You could expand is as a vector shape to fix it.

I like the concept of this illustration, but I find it hard to read because of the angle and the fact that the search modal is just a blank rectangle.

Maybe using a vertical illustration, a bit tilted to the right, and filling the search modal would work better. Also, it doesn't need to be hi-fi, you could use a simplified style for it, similar to skeleton placeholders.

This keyboard illustration is blurry, even on my Retina screen. Also, the top of the image is cropped.

It's worth checking with the design team if we have an account on Adobe Stock or similar, to grab a crisper image (like this one).

Headings are misaligned because illustrations aren't of the same height.

In one-line paragraphs, the icon doesn't align well.

In the Algolia documentation there's a rule against exclamation marks (Google Developer style guide rule). This isn't documentation content, but exclamation marks in copywriting are a bit tacky. I'd recommend against them.

Documentation

This shouldn't be a docs page, but a standalone one.

This is an odd, not very searchable heading.

This admonition is too tone-on-tone, we can barely see it.

These collapse widgets don't look as good as the rest, and the open/close transition is a bit slow.

[HonkingGoose]

Here you go, some free grammar and typo fixes. 😉

[netlify]

✔️ Deploy Preview for docsearch ready!

🔨 Explore the source changes: 3a0ec24

🔍 Inspect the deploy log: https://app.netlify.com/sites/docsearch/deploys/615eca4dcb64820007d70927

😎 Browse the preview: https://deploy-preview-1048--docsearch.netlify.app