Skip to content

Minor tweaks to website#6264

Merged
arcanis merged 10 commits intoyarnpkg:masterfrom
clemyan:website/tweaks
Jun 19, 2024
Merged

Minor tweaks to website#6264
arcanis merged 10 commits intoyarnpkg:masterfrom
clemyan:website/tweaks

Conversation

@clemyan
Copy link
Member

@clemyan clemyan commented May 2, 2024 •
edited
Loading

What's the problem this PR addresses?

Some minor/nitpick-level problems with the website

Note: This PR has some overlap with #6218. I'll rebase one when the other is merged

How did you fix it?

  • Removed remnants of TypeScript misconfiguration created when first adding the docusaurus workspace via create-docusaurus
  • Reorganized the directory structure of the docusaurus workspace. In particular, moved stuff that is run in build-time (except the docusaurus.config.ts itself) to a config directory. May not seem like much but as more stuff gets added this can keep thing clean and manageable.
  • Used admonitions instead of plain text where appropriate
  • Made the remark plugins apply to the CHANGELOG (they weren't before)
  • Cleaned up and reorganized the dependencies. Of course there are different schools of philosophy regarding what should count as a dependency vs devDependency in a frontend app. Ultimately I decided for Docusaurus, it makes more sense to say everything needed to run yarn build successfully is a dep and devDeps are those that are purely for DX (e.g. types)
  • Removed babel and browserslist config as we are not using them at all

Checklist

  • I have set the packages that need to be released for my changes to be effective.
  • I will check that all automated PR checks pass before the PR gets reviewed.

clemyan added 2 commits May 3, 2024 00:21
@clemyan
fix(docs): Fix lint errors
7135ebf
@clemyan
fix(docs): Rollback client bundle ES version bump
d580675 
I bumped the client bundle ES version based on the original browserslist
config (which was not used). On second thought, let's not introduce a
potentially breaking change in this PR.
merceyz
merceyz requested changes May 4, 2024
View reviewed changes
tsconfig.json Outdated
Comment on lines 4 to 5
"target": "ES2022",
"lib": ["ES2023"],
Copy link
Member

@merceyz merceyz May 4, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a breaking change.

Copy link
Member Author

@clemyan clemyan May 5, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was under the impression that the ES bump isn't because that's what TypeScript recommends for Node 18 and is supported by node.green. Turns out, they are both wrong.

Removing the DOM lib should be safe though? It was added in #4851, most likely because create-docusaurus was run on the root instead of under the docusaurus workspace.

@arcanis arcanis requested a review from merceyz May 6, 2024 08:56
@clemyan
Copy link
Member Author

clemyan commented May 7, 2024 •
edited
Loading

Oh and I forgot to mention, regarding the dependencies, there are a few that I don't know what to do with them

  • @codesandbox/sandpack-react: as far as I can tell this was used for the sherlock playground? I tried to remove it but that would remove a lot of transitive deps and I am weary of introducing churn if and when we rebuild the playground.
  • markdown-it-br and marked-base-url: these are plugins to markdown-it and marked respectively? They are not imported anywhere but I don't know how markdown-it and marked discover/load plugins so I'm not sure whether they are used or not.

For this PR I'm not touching them since there is no harm but I'm generally all for removing unnecessary deps.

Also, in theory, all the default plugins are dependencies of the docusaurus workspace because they are needed to generate the CLI docs. So, in theory we should list all of them as dependencies. This would have the benefit that (together with this PR) that the website can be built with a production-only focused docusaurus workspace but I'm not sure if the maintainence burden is worth that.

Side quesetion: Why is the website built with --no-minify on Netlify?

@arcanis
Copy link
Member

arcanis commented Jun 19, 2024

Side quesetion: Why is the website built with --no-minify on Netlify?

I don't remember a particular reason 🤔

@arcanis arcanis merged commit 40b5fb8 into yarnpkg:master Jun 19, 2024
@clemyan clemyan deleted the website/tweaks branch July 14, 2024 03:52
@clemyan clemyan mentioned this pull request Apr 28, 2025
Merged
3 tasks
arcanis pushed a commit that referenced this pull request May 9, 2025
@clemyan
Docusaurus: Update Docusaurus to 3.7 (#6777)
e8fbb0c 
## What's the problem this PR addresses?

The Docusaurus version we use is not the latest

## How did you fix it?

Upgrades Docusuaurs to 3.7 and start using the new features:

- Also upgrade `docusaurus-plugin-typedoc-api` for compatibility
- `docusaurus-plugin-typedoc-api` is unmaintined now. Maybe we should
make our custom solution eventually?
- Upgrade React to v19 since Docusuaurs 3.7 supports it now
- Also upgrades other libraries for official compatibility with React
19, which, while maybe not strictly necessary (nothing seems to break
without those upgrades), is nice to get out of the way
- Upgrade `xterm` so the website can be built with Node 22
- Bump the Netlify build to Node 22, as Node 18 will be EOL this week.
- Add truncation of blog posts on the main blog feed (recommended by
Docusaurus)
- Add author social links to blog posts (@arcanis I just copied the
socials from your website, expect replacing Twitter with BlueSky and
adding the website itself. Please review if there are changes you'd like
to make)
- Remove the extraneous dependencies that [weren't
removed](#6264 (comment))
in #6264.
- Now I'm pretty sure `markdown-it-br` and `marked-base-url` is actually
usused
- Even if we are to rebuild the sherlock playground, I feel like there
are better libraries for that then `@codesandbox/sandpack-react`. Even
if we use `@codesandbox/sandpack-react` again we'd probably use the
latest version which is a semver-major bump so there will be churn
either way.
- Minor fixes like fixing backgrounds

I have done some visual comparison testing to verify there aren't
unexpected visual changes (on the pages I checked at least)

----

Questions:
- Docusaurus's perf logger now records memory usage. Maybe we should
turn that on on Netlify?
- Do we want to start migrating to `compressionLevel: 0` (the default
since 4.0)? This PR replaces ~300 deps (out of ~2,100) so I feel like
that's a good time to do so *if* we are to migrate

## Checklist

<!--- Don't worry if you miss something, chores are automatically
tested. -->
<!--- This checklist exists to help you remember doing the chores when
you submit a PR. -->
<!--- Put an `x` in all the boxes that apply. -->
- [x] I have read the [Contributing
Guide](https://yarnpkg.com/advanced/contributing).

<!-- See
https://yarnpkg.com/advanced/contributing#preparing-your-pr-to-be-released
for more details. -->
<!-- Check with `yarn version check` and fix with `yarn version check
-i` -->
- [x] I have set the packages that need to be released for my changes to
be effective.

<!-- The "Testing chores" workflow validates that your PR follows our
guidelines. -->
<!-- If it doesn't pass, click on it to see details as to what your PR
might be missing. -->
- [x] I will check that all automated PR checks pass before the PR gets
reviewed.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@merceyz merceyz Awaiting requested review from merceyz

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@clemyan @arcanis @merceyz