Skip to content

chore(website): add 'Automated Rule Docs with Docusaurs and Remark' post #5593

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.

Sign up for GitHub

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

Jump to bottom
Merged
merged 16 commits into from
Sep 19, 2022
Merged

chore(website): add 'Automated Rule Docs with Docusaurs and Remark' post #5593

merged 16 commits into from
Sep 19, 2022

Conversation

JoshuaKGoldberg
Copy link
Member

@JoshuaKGoldberg JoshuaKGoldberg commented Sep 3, 2022 •
edited
Loading

PR Checklist

Overview

Enables the Docusaurus blog preset with a single article about how we automated rule docs (#5386).

@typescript-eslint
Copy link
Contributor

Thanks for the PR, @JoshuaKGoldberg!

typescript-eslint is a 100% community driven project, and we are incredibly grateful that you are contributing to that community.

The core maintainers work on this in their personal time, so please understand that it may not be possible for them to review your work immediately.

Thanks again!

🙏 Please, if you or your company is finding typescript-eslint valuable, help us sustain the project by sponsoring it transparently on https://opencollective.com/typescript-eslint. As a thank you, your profile/company logo will be added to our main README which receives thousands of unique visitors per day.

@nx-cloud
Copy link

nx-cloud bot commented Sep 3, 2022 •
edited
Loading

☁️ Nx Cloud Report

CI is running/has finished running commands for commit d1f9fb0. As they complete they will appear below. Click to see the status, the terminal output, and the build insights.

📂 See all runs for this branch

✅ Successfully ran 47 targets

Sent with 💌 from NxCloud.

@netlify
Copy link

netlify bot commented Sep 3, 2022 •
edited
Loading

✅ Deploy Preview for typescript-eslint ready!

Name Link
🔨 Latest commit d1f9fb0
🔍 Latest deploy log https://app.netlify.com/sites/typescript-eslint/deploys/6328711a4ddd8b0008b88d57
😎 Deploy Preview https://deploy-preview-5593--typescript-eslint.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site settings.

@JoshuaKGoldberg JoshuaKGoldberg marked this pull request as ready for review September 3, 2022 04:59
Josh-Cena
Josh-Cena reviewed Sep 4, 2022
View reviewed changes
Copy link
Member

@Josh-Cena Josh-Cena left a comment

Choose a reason for hiding this comment

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

Thanks for mentioning me! I have some copy edit suggestions

packages/website/blog/2022-09-03-automated-rule-docs-with-docusaurus-and-remark.md Outdated
Docusaurus supports MDX using [remark](https://remark.js.org), a Markdown processor powered by plugins.
Remark plugins take in Markdown files in a format known as an Abstract Syntax Trees, or AST, and output modified versions of those ASTs.

You can see what Remark's AST equivalent of a Markdown document looks like by visiting [AST Explorer](https://astexplorer.net) and selecting the Markdown language.
Copy link
Member

Choose a reason for hiding this comment

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

I strongly suggest adding https://mdx-git-renovate-babel-monorepo-mdx.vercel.app/playground here—I think you fell on the type: "jsx" node because you were not using the MDX playground 😄

Copy link
Member Author

Choose a reason for hiding this comment

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

And thus we hit the classic issue in frontend tooling of a million tools, each out of date and/or wrong in their own unique way...

Screenshot of a header saying '🎉 MDX Conf - August 24th, 2020'

For my edification, what's the different/problem with astexplorer.net? Since astexplorer.net is such as great & widely used tool, I'd rather fix the issue there if possible.

Copy link
Member

@Josh-Cena Josh-Cena Sep 4, 2022 •
edited
Loading

Choose a reason for hiding this comment

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

AST explorer using Remark, not MDX. <div /> produces type: "html" in Remark, but type: "jsx" in MDX. import is also only supported in MDX. AST explorer's MDX mode only shows MDXHAST for some reason, without the MDXAST. Docusaurus' own docs recommend using the MDX playground.

(The "website" there is actually a deploy preview snapshot. We are using it because mdxjs.com is now only hosting MDX v2)

Copy link
Member Author

Choose a reason for hiding this comment

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

Got it, thanks - my main hiccup is I don't want to link to something that still references a conference from two years ago. If you can get that updated / removed then I'm happy to link!

JoshuaKGoldberg and others added 2 commits September 4, 2022 12:16
@JoshuaKGoldberg @Josh-Cena
Apply suggestions from code review
95d46fd 
Co-authored-by: Joshua Chen <sidachen2003@gmail.com>
@JoshuaKGoldberg
Little fixups, and cleaner config
3b7e5dc
JoshuaKGoldberg and others added 2 commits September 4, 2022 15:44
@JoshuaKGoldberg @Josh-Cena
Update packages/website/blog/2022-09-03-automated-rule-docs-with-docu…
236979e 
…saurus-and-remark.md

Co-authored-by: Joshua Chen <sidachen2003@gmail.com>
@JoshuaKGoldberg
figcaption
56762c1
@bradzacher bradzacher added the package: website Issues related to the @typescript-eslint website label Sep 4, 2022
@bradzacher bradzacher changed the title feat(website): add 'Automated Rule Docs with Docusaurs and Remark' post chore(website): add 'Automated Rule Docs with Docusaurs and Remark' post Sep 4, 2022
bradzacher
bradzacher previously approved these changes Sep 19, 2022
View reviewed changes
Copy link
Member

@bradzacher bradzacher left a comment

Choose a reason for hiding this comment

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

image

bradzacher
bradzacher previously approved these changes Sep 19, 2022
View reviewed changes
@JoshuaKGoldberg
Copy link
Member Author

Or, I'll just admin merge...

@JoshuaKGoldberg JoshuaKGoldberg merged commit 0a63967 into typescript-eslint:main Sep 19, 2022
@JoshuaKGoldberg JoshuaKGoldberg deleted the blog-automated-rule-docs branch September 19, 2022 14:05
@github-actions github-actions bot locked as resolved and limited conversation to collaborators Oct 20, 2022
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Reviewers

@Josh-Cena Josh-Cena Josh-Cena left review comments

@bradzacher bradzacher Awaiting requested review from bradzacher

Assignees
No one assigned
Labels
package: website Issues related to the @typescript-eslint website
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

Docs: Add a blog to the website
3 participants
@JoshuaKGoldberg @bradzacher @Josh-Cena