diff --git a/site/content/docs/custom-components.md b/site/content/docs/custom-components.md
deleted file mode 100644
index 2d072f482..000000000
--- a/site/content/docs/custom-components.md
+++ /dev/null
@@ -1,68 +0,0 @@
-# Adding custom components to your markdown
-
-## Steps
-
-1. Create a component in `/components` folder:
-```js
-// Demo.js
-export default function DemoComponent() {
- return (
-
-
I'm a custom component!
-
- )
-}
-```
-
-2. Import it in `components/MDX.js` file and add it to `components` object.
-```javascript
-// MDX.js
-import DemoComponent from './DemoComponent.js'
-
-const components = {
- ...
- DemoComponent,
- ...
-}
-```
-
-3. Use directly in your markdown file.
-```md
-# Here is an example of a custom component
-
-
-```
-
-## Passing data to your custom components
-
-1. Add the data in `pages/[[slug]].js`
-```javascript
-// [[slug.js]]
-const testData = [
- { title: "First", value: 1 },
- { title: "Second", value: 2 },
- { title: "Third", value: 3 },
-]
-
-export default function Page({ body, ...rest }) {
- const Component = useMDXComponent(body.code, { testData });
- // ...
-}
-```
-
-2. Use as props value in markdown
-```javascript
-
-```
-
-## Example
-Note, that the code we've used for the above examples was simplified, so the component below will be slightly different.
-
-```md
-
-```
-
-This will render as:
-
-
-
diff --git a/site/content/docs/mdx.md b/site/content/docs/mdx.md
new file mode 100644
index 000000000..2302f2c4c
--- /dev/null
+++ b/site/content/docs/mdx.md
@@ -0,0 +1,288 @@
+import { Callout } from '../components/TempCallout.jsx'
+
+# MDX
+
+Flowershow parses all of your Markdown files as MDX. This means you not only can write your content using good old Markdown, but also extend it with JSX, JavaScript expressions, and `import` and `export` statements. It's basically Markdown on steroids ππͺ!
+
+Let's see what exactly is MDX and what's so cool about it!
+
+
+ A basic familiarity with JSX (React components) and JavaScript might be helpful to understand this chapter, but you can also learn by example and start by tweaking some of our code. Opening this page in your text editor side by side with the rendered version in your browser may also help.
+
+
+## What is MDX?
+
+From the official [MDX docs](https://mdxjs.com/docs/what-is-mdx/):
+
+> MDX can be explained as a format that combines markdown with JSX.
+
+It looks like this:
+```md
+# Hello, world!
+
+
+ > Some notable things in a block quote!
+
+```
+
+You may be thinking: *"Hold on, but isn't it just some Markdown with an HTML block wrapping around some more Markdown... which is a standard CommonMark syntax?"*
+
+The answer to this question is - yes... and no Β―\_(γ)_/Β―.
+
+**Yes**, because it really is a CommonMark syntax, which allows you to add HTML parts and even intertwine them with Markdown like in our example. You may have written something similar without even hearing about MDX and if you're starting your new Flowershow project with your existing Markdown content - it will all work! This is because MDX supports CommonMark by default. Additionally, Flowershow provides support for GFM (GitHub Flavored Markdown) and some Obsidian-specific syntax elements. (See our [[syntax|Syntax]] guide to learn more.)
+
+**No**, because Flowershow will parse all your Markdown files as MDX (no matter if you use `.md` or `.mdx` file extension). This means that in the example above, the heading and the block quote will be treated as Markdown, however, the HTML-like looking `
` tag will be understood as **JSX** - a React syntax extension to JavaScript that looks like HTML, which allows you to create and use components in your Markdown files.
+
+
+ βYou may have noticed, that we haven't used an HTML `class` attribute on the `
` tag above, but rather React's `className` attribute. This is because all HTML elements will be parsed as JSX, which will then be used by React's runtime to render your pages.
+
+
+How does it work? In short, packages used by Flowershow under the hood compile MDX to JavaScript, which is then used by React to create your website.
+
+## MDX supported syntax
+
+The following sections are just short summaries of what MDX can do. Read [the official MDX docs](https://mdxjs.com/) to learn more.
+
+
+ βIn this document we're going to use Markdown and MDX, as well as HTML and JSX interchangeably. The reason for this is the fact that Flowershow, as we've just learned, parses all Markdown files as MDX files. So, from your perspective, it may be only Markdown that you're using to write your content. However, Flowershow will also understand any MDX-specific additions to it if you were to include them. It follows, that what you may consider HTML blocks, in MDX world is JSX.
+
+
+### Markdown
+
+As we've mentioned, MDX supports CommonMark syntax by default. On top of that Flowershow provides support for GFM and some Obsidian-specific extensions. Check our [syntax|Syntax guide] to learn which other Markdown syntax elements are supported by Flowershow.
+
+### JSX and custom components
+
+JSX allows you to create components, that you can reuse across all of your markdown files. This is especially useful if you find yourself writing a lot of custom HTML in your Markdown, and/or you use the same HTML code parts and copy them again and again to different markdown pages. You soon may find it difficult to tell what a given part of HTML block is supposed to do. And what used to be e.g. your blog content ends up as a Markdown-HTML-CSS soup. On top of that, imagine if you wanted to make some changes to all these copies of HTML blocks, that you used many different pages π€―.
+
+Fortunately, thanks to JSX you can extract common HTML parts and enclose them in components, which you can then import and use wherever you want in your Markdown. What you end up with is much cleaner content and a single source of truth for HTML (JSX) parts you used to copy over and over again. JSX components allow you to declutter your Markdown and to separate content writing from its structuring and styling π.
+
+For example, by creating a component out of a part of HTML code you repeat all over again, you could turn this...
+
+```md
+# Some page heading
+
+Some content here...
+
+
+
+
+
+Some more content here...
+```
+
+...into to this:
+
+
+```md
+# Some page heading
+
+Some content here...
+
+
+
+Some more content here...
+```
+
+Looks much better! And it's much easier to update if you're using this button on many different pages.
+
+(We'll learn more about how to create, import, and use your custom components in the sections below.)
+
+### ESM `import` and `export` statements
+
+This is where a lot of MDX power comes from: support for ESM (ECMAScript Modules) `import` and `export` statements, which you can use to import custom JSX (React) components or even define them locally, as well as import and locally define data (variables), that can then be passed to your JSX components.
+
+#### Importing components
+
+To see this in action, let's create a React component in the `/components` folder:
+
+```js
+// MyComponent.jsx
+export const MyComponent = ({ list }) => {
+ return (
+
+
I'm a custom react component imported into this page!
+
+
And here is a list of some things passed to me through props:
+
+ { list.map((x, i) =>
{x}
) }
+
+
+
+ )
+}
+```
+
+
+β Note, that you should use a `.jsx` extension for any components you want to import into markdown files to make it work.
+
+
+Now, let's import `MyComponent` into this page's markdown.
+
+```md
+import { MyComponent } from '../components/MyComponent.jsx'
+
+
+
+Hooray! π
+```
+
+The above MDX code renders as:
+
+---
+
+import { MyComponent } from '../components/MyComponent.jsx'
+
+
+
+Hooray! π
+
+---
+
+#### Importing data
+
+Another powerful thing you can do thanks to `import` statements is loading data from external files.
+
+Let's try to load a list of colors from a JSON file and pass it as a `list` prop value to our component `MyComponent`:
+
+```md
+import data from '../data/exampleData.json'
+
+
+```
+
+This will render as:
+
+---
+
+import data from '../data/exampleData.json'
+
+
+
+---
+
+The above is just a simple example, but imagine creating a custom `Chart` component for which you could import an external dataset and use it to plot data for your research notes π₯!
+
+#### Defining components locally
+If the component you're creating will be used only on one of your pages, but either it will be repeated multiple times or it's a complex one and you want to keep it at the very top/bottom of your page so that it doesn't clutter your content, you could define a component locally. To do this you can use ESM `export` statement.
+
+For example, instead of creating the above component `MyComponent` in a separate `.jsx` file, let's do the following:
+
+```md
+export const MyComponent2 = ({ list }) => {
+ return (
+