-
Notifications
You must be signed in to change notification settings - Fork 402
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
feat(website): new documentation #1048
Conversation
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:
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
url: https://github.com/shortcuts | ||
--- | ||
|
||
To help you create the best search experience for your users, we provide config templates for multiple websites generators. If you'd like to add a new template to our list, or believe we should update an existing one, please [send us an email][1] or [open a pull request][2] |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I would emphasis that all of them are accesible in the Crawler UI
And also that they are Crawler config.
A screenshot can help
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! |
I love it! Let's go team! |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Co-authored-by: François Chalifour <francoischalifour@users.noreply.github.com> Co-authored-by: Samuel Bodin <samuel.bodin@algolia.com>
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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 |
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Massive 🏋🏻
I have made a few suggestions, I'm not technical writer so feel free to discard it's just my own feeling.
|
||
:::note | ||
|
||
This documentation will only contain informations regarding the **helpers.docsearch** method, see **[Algolia Crawler Documentation][7]** for more informations on the **[Algolia Crawler][8]**. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This might be good to document it in our main Doc too, as we are now exposing it to everyone
DocSearch can work with almost any website, but we've found that some site | ||
structures yield more relevant results or faster indexing time. In this page | ||
we'll share some tips on how you can make the most out of DocSearch. | ||
DocSearch can work with almost any website, but we've found that some site structures yield more relevant results or faster indexing time. In this page we'll share some tips on how you can make the most out of DocSearch. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This page seems really similar to the end of packages/website/docs/required-configuration.mdx
maybe you could gather the content
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 modeThe 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.movIllustrations and iconsSome 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. DocumentationThis 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. |
Co-authored-by: Samuel Bodin <samuel.bodin@algolia.com> Co-authored-by: François Chalifour <francoischalifour@users.noreply.github.com>
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Here you go, some free grammar and typo fixes. 😉
packages/website/versioned_docs/version-legacy/required-configuration.md
Outdated
Show resolved
Hide resolved
packages/website/versioned_docs/version-legacy/required-configuration.md
Outdated
Show resolved
Hide resolved
packages/website/versioned_docs/version-legacy/required-configuration.md
Outdated
Show resolved
Hide resolved
packages/website/versioned_docs/version-legacy/required-configuration.md
Outdated
Show resolved
Hide resolved
Co-authored-by: HonkingGoose <34918129+HonkingGoose@users.noreply.github.com>
✔️ 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 |
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
documentationAll of the actual documentation (minus references of the previous infra) is still available.
current
documentationhelpers.docsearch
extractor method, API and a few exampleslegacy
tocurrent
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
README
s have been updated with the new documentation links and a similar format to what we've done in AutocompleteTODO
How to test
yarn && yarn website:start
When to merge
We will wait for the migration to officially start before publishing the new documentation