Skip to content

Commit

Permalink
Refactor more docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@wooorm
wooorm committed Oct 24, 2023
1 parent 0d1558a commit bc1d9e5
Show file tree
Hide file tree
Showing 41 changed files with 2,301 additions and 2,246 deletions.
11 changes: 7 additions & 4 deletions docs/_asset/editor.jsx
View file
Expand Up @@ -93,12 +93,12 @@ const grammars = [
/** @type {Awaited<ReturnType<typeof createStarryNight>>} */
let starryNight

const body = document.querySelector('.body')
const editor = document.querySelector('#js-editor')

if (body && window.location.pathname === '/playground/') {
if (window.location.pathname === '/playground/' && editor) {
const root = document.createElement('div')
root.classList.add('playground')
body.after(root)
editor.after(root)
init(root)
}

Expand Down Expand Up @@ -204,7 +204,10 @@ function Playground() {

if (show === 'result') {
/** @type {MDXModule} */
const mod = await run(String(file), runtime)
const mod = await run(String(file), {
...runtime,
baseUrl: window.location.href
})

return (
<ErrorBoundary FallbackComponent={ErrorFallback}>
Expand Down
12 changes: 10 additions & 2 deletions docs/_asset/index.css
View file
Expand Up @@ -331,7 +331,6 @@ hr {
table {
border-collapse: collapse;
border-spacing: 0;
display: block;
overflow: auto;
width: 100%;
font-variant-numeric: lining-nums;
Expand Down Expand Up @@ -539,6 +538,16 @@ button.success {
);
}

.full-bleed {
width: 100vw;
position: relative;
left: 50%;
right: 50%;
margin-left: -50vw;
margin-right: -50vw;
padding-inline: calc(1em + 1ex);
}

/* Note that the `backdrop-filter` itself is applied in light mode. */
@supports (backdrop-filter: blur(1ex)) {
.navigation::before {
Expand Down Expand Up @@ -1224,7 +1233,6 @@ details[open] {
grid-template-columns: 49% 49%;
min-height: 40rem;
gap: calc(1em + 1ex);
margin-inline: calc(1em + 1ex);
}

.playground-area,
Expand Down
6 changes: 2 additions & 4 deletions docs/_config.js
View file
Expand Up @@ -38,13 +38,11 @@ export const redirect = {
'/contributing/index.html': '/community/contribute/',
'/editor-plugins/index.html': '/docs/getting-started/#editor',
'/editors/index.html': '/docs/getting-started/#editor',
'/getting-started/create-react-app/index.html':
'/docs/getting-started/#create-react-app-cra',
'/getting-started/create-react-app/index.html': '/docs/getting-started/#vite',
'/getting-started/gatsby/index.html': '/docs/getting-started/#gatsby',
'/getting-started/next/index.html': '/docs/getting-started/#nextjs',
'/getting-started/parcel/index.html': '/docs/getting-started/#parcel',
'/getting-started/react-static/index.html':
'/docs/getting-started/#react-static',
'/getting-started/react-static/index.html': '/docs/getting-started/#vite',
'/getting-started/table-of-components/index.html': '/table-of-components/',
'/getting-started/typescript/index.html': '/docs/getting-started/#types',
'/getting-started/webpack/index.html': '/docs/getting-started/#webpack',
Expand Down
78 changes: 39 additions & 39 deletions docs/blog/v1.mdx
View file
Expand Up @@ -77,12 +77,12 @@ for implementing this feature.
**Good libraries need great docs**, so we’ve been working on adding content and
improving the overall documentation website experience.

* [Search (thanks Algolia)](https://mobile.twitter.com/4lpine/status/1114270174096412672)
* [Guides](/guides/)
* [Automatic deployment via ZEIT](https://zeit.co)
* [Custom Gatsby theme](https://gatsbyjs.org)
* Reorganization of docs for intuitiveness
* Full page rewrites to improve clarity
* [Search (thanks Algolia)](https://mobile.twitter.com/4lpine/status/1114270174096412672)
* [Guides](/guides/)
* [Automatic deployment via ZEIT](https://zeit.co)
* [Custom Gatsby theme](https://gatsbyjs.org)
* Reorganization of docs for intuitiveness
* Full page rewrites to improve clarity

Special thanks to [@jxnblk](https://github.com/jxnblks) and
[@wooorm](https://github.com/wooorm) for their help improving the docs and
Expand All @@ -97,12 +97,12 @@ The community has evolved and we’ve come up with newer, better ideas over the
last year.
We have made sure the impact is small and have written a full migration guide.

* 🚨`@mdx-js/tag` is replaced by `@mdx-js/react` and an `@mdx` pragma
— [migration guide](/migrating/v1#pragma)
* MDXProvider now merges component contexts when nested
— [migration guide](/migrating/v1#mdxprovider)
* React support now requires `>= 16.8` in `@mdx-js/react`
— [migration guide](/migrating/v1#react)
* 🚨`@mdx-js/tag` is replaced by `@mdx-js/react` and an `@mdx` pragma
— [migration guide](/migrating/v1#pragma)
* MDXProvider now merges component contexts when nested
— [migration guide](/migrating/v1#mdxprovider)
* React support now requires `>= 16.8` in `@mdx-js/react`
— [migration guide](/migrating/v1#react)

[Read the full v1 migration guide](/migrating/v1)

Expand All @@ -123,11 +123,11 @@ We’ve also seen projects/products/application we never even imagined.

### Numbers

* **Downloads**: 125,000/week, 2.4M total
* **Stars**: 6,200
* **Contributors**: 50
* **Pull requests**: 281
* **Commits**: 670
* **Downloads**: 125,000/week, 2.4M total
* **Stars**: 6,200
* **Contributors**: 50
* **Pull requests**: 281
* **Commits**: 670

The contributor growth is one of the most important aspects here as we have
numerous community members that are familiar with MDX internals.
Expand All @@ -138,30 +138,30 @@ against an ever growing team of contributors.

### Ecosystem

* [Prettier](https://prettier.io)
* [Docz](https://docz.site)
* [MDX Deck](https://github.com/jxnblk/mdx-deck)
* [Next.js](https://nextjs.org)
* [Gatsby](https://gatsbyjs.org)
* [AST Explorer](https://astexplorer.net)
* [Vue support (alpha)](/docs/getting-started/#vue)
* [Demoboard](https://frontarm.com/demoboard/)
* [Editors](/docs/getting-started/#editor)
* [Prettier](https://prettier.io)
* [Docz](https://docz.site)
* [MDX Deck](https://github.com/jxnblk/mdx-deck)
* [Next.js](https://nextjs.org)
* [Gatsby](https://gatsbyjs.org)
* [AST Explorer](https://astexplorer.net)
* [Vue support (alpha)](/docs/getting-started/#vue)
* [Demoboard](https://frontarm.com/demoboard/)
* [Editors](/docs/getting-started/#editor)

## 🛣 Roadmap

With v1 released we have a roadmap in place that we’ll continue working towards
over the next 6 months or so in addition to bug fixes and parsing issues we
might encounter.

* MDXs: [#454](https://github.com/mdx-js/mdx/issues/454)
* Interleaving: [#195](https://github.com/mdx-js/mdx/issues/195)
* Global shortcodes: [#508](https://github.com/mdx-js/mdx/pull/508)
* Stable Vue support: [#238](https://github.com/mdx-js/mdx/issues/238)
* Blocks: MDX WYSIWYG: [blocks/blocks](https://github.com/blocks/blocks)
* MDX playground inspired by AST Explorer: [#220](https://github.com/mdx-js/mdx/issues/220)
* New splash page: [#444](https://github.com/mdx-js/mdx/issues/444)
* Showcase page: [#414](https://github.com/mdx-js/mdx/issues/414)
* MDXs: [#454](https://github.com/mdx-js/mdx/issues/454)
* Interleaving: [#195](https://github.com/mdx-js/mdx/issues/195)
* Global shortcodes: [#508](https://github.com/mdx-js/mdx/pull/508)
* Stable Vue support: [#238](https://github.com/mdx-js/mdx/issues/238)
* Blocks: MDX WYSIWYG: [blocks/blocks](https://github.com/blocks/blocks)
* MDX playground inspired by AST Explorer: [#220](https://github.com/mdx-js/mdx/issues/220)
* New splash page: [#444](https://github.com/mdx-js/mdx/issues/444)
* Showcase page: [#414](https://github.com/mdx-js/mdx/issues/414)

### Vue support

Expand Down Expand Up @@ -196,11 +196,11 @@ dealing with many sources of content.
unified projects are used all over the web, and it would never be possible
without financial support from our fine sponsors.

* [ZEIT](https://zeit.co) 🥇
* [Gatsby](https://gatsbyjs.org) 🥇
* [Holloway](https://www.holloway.com) 🥉
* [Backers](https://opencollective.com/unified#budget) 🏆
* [You?](https://opencollective.com/unified)👤
* [ZEIT](https://zeit.co) 🥇
* [Gatsby](https://gatsbyjs.org) 🥇
* [Holloway](https://www.holloway.com) 🥉
* [Backers](https://opencollective.com/unified#budget) 🏆
* [You?](https://opencollective.com/unified)👤

## 🙏 Thanks

Expand Down
36 changes: 18 additions & 18 deletions docs/blog/v2.mdx
View file
Expand Up @@ -21,17 +21,17 @@ Here are the highlights:
{/* more */}

<div className="emoji-list">
* 📝 **Improved syntax** makes it easier to use markdown in JSX
* 🧑‍💻 **JavaScript expressions** turn `{2 * Math.PI}` into {2 * Math.PI}
* 🔌 New **esbuild**, **Rollup**, and **Node.js** integrations
* ⚛️ **Any JSX runtime**: React, Preact, Vue, Emotion, you name it, they’re
all supported
* 🌳 **Improved AST** exposes more info in greater detail
* 🏃‍♀️ Compiles at least **25% faster**
* 🚴 Generated code runs twice as fast (**100% faster**)
* 🚄 Bundle size of `@mdx-js/mdx` is more than three times as small
(**250% smaller**)
* 🧵 …and much, so much more
* 📝 **Improved syntax** makes it easier to use markdown in JSX
* 🧑‍💻 **JavaScript expressions** turn `{2 * Math.PI}` into {2 * Math.PI}
* 🔌 New **esbuild**, **Rollup**, and **Node.js** integrations
* ⚛️ **Any JSX runtime**: React, Preact, Vue, Emotion, you name it, they’re
all supported
* 🌳 **Improved AST** exposes more info in greater detail
* 🏃‍♀️ Compiles at least **25% faster**
* 🚴 Generated code runs twice as fast (**100% faster**)
* 🚄 Bundle size of `@mdx-js/mdx` is more than three times as small
(**250% smaller**)
* 🧵 …and much, so much more
</div>

It’s been 4 years since this project was announced.
Expand All @@ -41,13 +41,13 @@ Let’s dive in!

## Contents

* [Improvements to the MDX format](#improvements-to-the-mdx-format)
* [Rollup, esbuild, and other integrations](#rollup-esbuild-and-other-integrations)
* [Architectural improvements](#architectural-improvements)
* [TypeScript](#typescript)
* [Docs & site](#docs--site)
* [Breaking changes](#breaking-changes)
* [Thanks](#thanks)
* [Improvements to the MDX format](#improvements-to-the-mdx-format)
* [Rollup, esbuild, and other integrations](#rollup-esbuild-and-other-integrations)
* [Architectural improvements](#architectural-improvements)
* [TypeScript](#typescript)
* [Docs & site](#docs--site)
* [Breaking changes](#breaking-changes)
* [Thanks](#thanks)

## Improvements to the MDX format

Expand Down
46 changes: 23 additions & 23 deletions docs/community/about.mdx
View file
Expand Up @@ -29,28 +29,28 @@ MDX solves this.
There are many languages objectively better than markdown, however, markdown is
great because:

* It looks like what it means and is relatively easy to read
* Although images are [confusing][], most stuff is relatively simple to write
* It’s loose and ambiguous: it may not work but you won’t get an error (great
for someone posting a comment to a forum if they forgot an asterisk)
* It looks like what it means and is relatively easy to read
* Although images are [confusing][], most stuff is relatively simple to write
* It’s loose and ambiguous: it may not work but you won’t get an error (great
for someone posting a comment to a forum if they forgot an asterisk)

Markdown *does* have a way to extend it, HTML, but that has drawbacks:

* HTML in markdown is naïve, how it’s parsed sometimes doesn’t make sense
* HTML is unsafe by default, so it’s sometimes (partially) unsupported
* HTML and markdown don’t mix well, resulting in confusing rules such as
blank lines or `markdown="1"` attributes
* HTML is coupled with browsers, markdown is useful for other things too
* HTML in markdown is naïve, how it’s parsed sometimes doesn’t make sense
* HTML is unsafe by default, so it’s sometimes (partially) unsupported
* HTML and markdown don’t mix well, resulting in confusing rules such as
blank lines or `markdown="1"` attributes
* HTML is coupled with browsers, markdown is useful for other things too

The frontend world has an alternative to HTML: JSX.
JSX is great, amongst other things, because:

* It has a relatively familiar syntax (like XML)
* It’s agnostic to semantics and intended for compilers (can have any
domain-specific meaning)
* It’s strict and unambiguous (great if an author forgot a slash somewhere, as
they’ll get an error early, instead of a book going to print with broken
stuff in it)
* It has a relatively familiar syntax (like XML)
* It’s agnostic to semantics and intended for compilers (can have any
domain-specific meaning)
* It’s strict and unambiguous (great if an author forgot a slash somewhere, as
they’ll get an error early, instead of a book going to print with broken
stuff in it)

## Who governs MDX?

Expand Down Expand Up @@ -104,17 +104,17 @@ The following projects inspired `@mdx-js/*` originally:

{/* Note: please keep the original project names intact: */}

* [`jamesknelson/mdxc`](https://github.com/frontarm/mdx-util)
* [`ticky/markdown-component-loader`](https://github.com/ticky/markdown-component-loader)
* [`threepointone/markdown-in-js`](https://github.com/threepointone/markdown-in-js)
* [`fazouane-marouane/remark-jsx`](https://github.com/remarkjs/remark-jsx)
* [`mapbox/remark-react`](https://github.com/remarkjs/remark-react)
* [`rx-ts/eslint-mdx`](https://github.com/mdx-js/eslint-mdx)
* [`jamesknelson/mdxc`](https://github.com/frontarm/mdx-util)
* [`ticky/markdown-component-loader`](https://github.com/ticky/markdown-component-loader)
* [`threepointone/markdown-in-js`](https://github.com/threepointone/markdown-in-js)
* [`fazouane-marouane/remark-jsx`](https://github.com/remarkjs/remark-jsx)
* [`mapbox/remark-react`](https://github.com/remarkjs/remark-react)
* [`rx-ts/eslint-mdx`](https://github.com/mdx-js/eslint-mdx)

The following articles inspired `@mdx-js/*` originally:

* [IA Markdown Content Blocks](https://github.com/iainc/Markdown-Content-Blocks)
* [Idyll: Markup language for interactive documents](https://idyll-lang.org)
* [IA Markdown Content Blocks](https://github.com/iainc/Markdown-Content-Blocks)
* [Idyll: Markup language for interactive documents](https://idyll-lang.org)

[what]: /docs/what-is-mdx/

Expand Down

1 comment on commit bc1d9e5

@vercel
Copy link

@vercel vercel bot commented on bc1d9e5 Oct 24, 2023

Choose a reason for hiding this comment

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

Successfully deployed to the following URLs:

mdx – ./

mdx-git-main-mdx.vercel.app
mdx-mdx.vercel.app
v2.mdxjs.com
mdxjs.com

Please sign in to comment.