@astrojs/ mdx
Это содержимое пока не доступно на вашем языке.
This Astro integration enables the usage of MDX components and allows you to create pages as .mdx
files.
Why MDX?
Section titled Why MDX?MDX allows you to use variables, JSX expressions and components within Markdown content in Astro. If you have existing content authored in MDX, this integration allows you to bring those files to your Astro project.
Installation
Section titled InstallationAstro includes an astro add
command to automate the setup of official integrations. If you prefer, you can install integrations manually instead.
Run one of the following commands in a new terminal window.
If you run into any issues, feel free to report them to us on GitHub and try the manual installation steps below.
Manual Install
Section titled Manual InstallFirst, install the @astrojs/mdx
package:
Then, apply the integration to your astro.config.*
file using the integrations
property:
Editor Integration
Section titled Editor IntegrationFor editor support in VS Code, install the official MDX extension.
For other editors, use the MDX language server.
Usage
Section titled UsageVisit the MDX docs to learn about using standard MDX features.
MDX in Astro
Section titled MDX in AstroAdding the MDX integration enhances your Markdown authoring with JSX variables, expressions and components.
It also adds extra features to standard MDX, including support for Markdown-style frontmatter in MDX. This allows you to use most of Astro’s built-in Markdown features.
.mdx
files must be written in MDX syntax rather than Astro’s HTML-like syntax.
Using MDX wth content collections
Section titled Using MDX wth content collectionsTo include MDX files in a content collection, make sure that your collection loader is configured to load content from .mdx
files:
Using Exported Variables in MDX
Section titled Using Exported Variables in MDXMDX supports using export
statements to add variables to your MDX content or to export data to a component that imports it.
For example, you can export a title
field from an MDX page or component to use as a heading with {JSX expressions}
:
Or you can use that exported title
in your page using import
and import.meta.glob()
statements:
Exported Properties
Section titled Exported PropertiesThe following properties are available to a .astro
component when using an import
statement or import.meta.glob()
:
file
- The absolute file path (e.g./home/user/projects/.../file.mdx
).url
- The URL of the page (e.g./en/guides/markdown-content
).frontmatter
- Contains any data specified in the file’s YAML frontmatter.getHeadings()
- An async function that returns an array of all headings (<h1>
to<h6>
) in the file with the type:{ depth: number; slug: string; text: string }[]
. Each heading’sslug
corresponds to the generated ID for a given heading and can be used for anchor links.<Content />
- A component that returns the full, rendered contents of the file.- (any
export
value) - MDX files can also export data with anexport
statement.
Using Frontmatter Variables in MDX
Section titled Using Frontmatter Variables in MDXThe Astro MDX integration includes support for using frontmatter in MDX by default. Add frontmatter properties just as you would in Markdown files, and these variables are available to use in the template, and as named properties when importing the file somewhere else.
Using Components in MDX
Section titled Using Components in MDXAfter installing the MDX integration, you can import and use both Astro components and UI framework components in MDX (.mdx
) files just as you would use them in any other Astro component.
Don’t forget to include a client:directive
on your UI framework components, if necessary!
See more examples of using import and export statements in the MDX docs.
Custom components with imported MDX
Section titled Custom components with imported MDXWhen rendering imported MDX content, custom components can be passed via the components
prop.
Custom components defined and exported in an MDX file must be imported and then passed back to the <Content />
component via the components
property.
Assigning Custom Components to HTML elements
Section titled Assigning Custom Components to HTML elementsWith MDX, you can map Markdown syntax to custom components instead of their standard HTML elements. This allows you to write in standard Markdown syntax, but apply special component styling to selected elements.
Import your custom component into your .mdx
file, then export a components
object that maps the standard HTML element to your custom component:
Visit the MDX website for a full list of HTML elements that can be overwritten as custom components.
Configuration
Section titled ConfigurationOnce the MDX integration is installed, no configuration is necessary to use .mdx
files in your Astro project.
You can configure how your MDX is rendered with the following options:
Options inherited from Markdown config
Section titled Options inherited from Markdown configAll markdown
configuration options can be configured separately in the MDX integration. This includes remark and rehype plugins, syntax highlighting, and more. Options will default to those in your Markdown config (see the extendMarkdownConfig
option to modify this).
MDX does not support passing remark and rehype plugins as a string. You should install, import, and apply the plugin function instead.
extendMarkdownConfig
Section titled extendMarkdownConfig- Type:
boolean
- Default:
true
MDX will extend your project’s existing Markdown configuration by default. To override individual options, you can specify their equivalent in your MDX configuration.
For example, say you need to disable GitHub-Flavored Markdown and apply a different set of remark plugins for MDX files. You can apply these options like so, with extendMarkdownConfig
enabled by default:
You may also need to disable markdown
config extension in MDX. For this, set extendMarkdownConfig
to false
:
recmaPlugins
Section titled recmaPluginsThese are plugins that modify the output estree directly. This is useful for modifying or injecting JavaScript variables in your MDX files.
We suggest using AST Explorer to play with estree outputs, and trying estree-util-visit
for searching across JavaScript nodes.
optimize
Section titled optimize- Type:
boolean | { ignoreElementNames?: string[] }
This is an optional configuration setting to optimize the MDX output for faster builds and rendering via an internal rehype plugin. This may be useful if you have many MDX files and notice slow builds. However, this option may generate some unescaped HTML, so make sure your site’s interactive parts still work correctly after enabling it.
This is disabled by default. To enable MDX optimization, add the following to your MDX integration configuration:
ignoreElementNames
Section titled ignoreElementNames- Type:
string[]
Добавлено в:
@astrojs/mdx@3.0.0
Previously known as customComponentNames
.
An optional property of optimize
to prevent the MDX optimizer from handling certain element names, like custom components passed to imported MDX content via the components prop.
You will need to exclude these components from optimization as the optimizer eagerly converts content into a static string, which will break custom components that needs to be dynamically rendered.
For example, the intended MDX output of the following is <Heading>...</Heading>
in place of every "<h1>...</h1>"
:
To configure optimization for this using the ignoreElementNames
property, specify an array of HTML element names that should be treated as custom components:
Note that if your MDX file configures custom components using export const components = { ... }
, then you do not need to manually configure this option. The optimizer will automatically detect them.
Examples
Section titled Examples- The Astro MDX starter template shows how to use MDX files in your Astro project.