Home
Markdown and MDX
Learn how to author content in Illuminate with Markdown syntax and enrich it with MDX features.
Overview
All documentation pages must be .mdx files, which are rendered with
MDX, an advanced Markdown format with JSX component
support. GitHub Flavored Markdown (GFM) syntax
is supported by default.
Front matter
Every documentation page must include front matter in YAML format at the top of the document. The front matter is used to specify the title and description, which are displayed at the top of the page and used to populate the page metadata.
Properties
| Name | Type | Description |
|---|---|---|
title required | string | Title of the page. This will be used to render the level 1 heading (h1) in the article header, and the page title in the metadata. |
description | string | Brief description of the page content. This will render the text below the page title in the article header and the description in the metadata for SEO. If the description is not specified in the front matter, the site description in illuminate.config.js will be used for the metadata instead. |
Example
Paragraphs
Any non-blank line that cannot be converted to any other block-level element
will be rendered as a paragraph element in HTML. To force a line break without
creating a new paragraph, add <br/> at the end of the line.
Headings
Up to six heading levels are available that will be rendered as their
corresponding HTML heading tags. By default, the page title is rendered as a
level 1 heading (h1). Level 2 headings are used to generate the table of
contents navigation (labeled "on this page") for each page.
Tip
It is
best practice
to only have a single h1 element per page. Since the title is automatically
rendered from the front matter as an h1 element, you should only use heading
levels 2–6 in the body of your pages.
Lists
Lists can either be ordered (numbered), unordered (bullets), or a combination of both.
Ordered lists
To create an ordered list, start each line with a number followed by a period
and a space (such as 1. ). The numbers do not have to be in numerical order in
the Markdown. List items will render numerically in the final output,
regardless. Use a tab or at least two spaces to indent ordered list items.
Unordered lists
To create an unordered list, start each line with a hyphen and a space (such as
- ). Use a tab or three spaces to indent unordered list items.
Combination lists
Use tabs or three spaces to indent list items and nest different types of lists inside each other. Use four spaces in front of media and components on a new line to nest them inside of list items.
Links
Links can be used to link to internal or external pages. They can also link to specific sections with anchors. Illuminate will automatically detect whether a link is internal or external based on the URL format and render it accordingly. External links will have an icon to indicate that they will open in a new tab. Internal links will not have an icon.
Internal links
Internal links use relative paths to navigate to another page in the current website using React Router.
External links
External links go to a page outside of the current website, and open in a new tab, by default. You can assign a title to an external link or use an automatic link, which shows the destination URL.
Dividers
Dividers (also known as horizontal rules) are used to show a thematic break between paragraph-level elements.
Images
Images can be added to documents by using an inline image link. The image link uses the relative path to the location of the image file and can optionally include alt text and a title. The title will show when the reader hovers over the image.
Local images
Insert local images using the relative path of the image file, where that path is relative to the location of the file that the image is being added to.
Linked images
To insert images from another website, use the full URL of the image.
Code blocks
To create a simple code block, add three backticks (```) before and after
the code. Since all code blocks in Illuminate are rendered with Code Hike,
additional customization and features can be added to make code samples more
engaging.
Tip
Code blocks can be enhanced with syntax highlighting, file names, links, focus effects, and more. For instructions and examples on how to extend the functionality and appearance of your code blocks, refer to the Code Blocks guide.
Quotes
Quotes are used to show an extended quotation from a cited source and are
rendered as a <blockquote> in HTML. Similar to paragraphs, quotes must include
an empty line after the quoted text to separate it from the content that
follows. Start a quote with a "greater than" symbol (>) followed by a space.
Tables
Tables are used to display an arrangement of data in rows and columns.
Pipes(|) are used to separate columns. Three or more hyphens (---) are used
to create each column's header. Colons (:) are used around the hyphens to
change the text alignment to right-aligned or center-aligned.
Text formatting
Pieces of text can be emphasized in Markdown by styling them as bold, italic, strikethrough, code, or a combination of multiple styles. The HTML elements that are rendered have semantic meaning and may be read differently than intended by screen readers.
JSX components
You can mix Markdown with JSX components in React or HTML to enhance content. Make sure to include a blank line between the component tag and the Markdown content.
Built-in components
Illuminate comes included with the following built-in components:
Use Accordion components in your documentation to organize supplemental
content in collapsible panels.
Use Callout components to highlight important information in your
documentation.
Use Card components to organize and link content in your documentation.
Use Tab components to group similar content in your documentation.
Code Hike
Illuminate also includes Code Hike components to add additional features and interactivity to your code samples:
Use CH.Code to add standard Code Hike features and the ability to display
multiple code examples in a single code block.
Use CH.Scrollycoding to show the code and corresponding text side-by-side.
Use CH.Section to reference pieces of code by grouping them with the
corresponding text in a section.
Use CH.Slideshow to wrap text and code into separate slides with buttons to
navigate between slides.
Use CH.Spotlight to change the code view based on linked sections of text.