Getting started
Step 1: Sign in
Head over to motif.land/login, enter your email, and confirm the login link sent to your inbox. Jump back to the Motif app.
Step 2: Choose the Ribbon Docs (Markdoc) template
Create a new team, and a new project. Give your project a name, and select the "Ribbon Docs (Markdoc)" template. Then hit "Create project".

Step 3: Enter writing mode
By default, the Motif sidebar will show the entire project content, including project configuration files, templates, stylesheets and components. Since you will be mainly focused on creating new pages, we recommend you to change the view to only show the content of the pages
folder. This is done by clicking on the "Source" menu at the bottom left of the screen, and selecting "Pages":

You are now ready to create and publish content!
Howtos
Basics
How do I create a Markdoc page?
Hit the "+" button at the bottom of the sidebar, select "New file", and add the mdoc
extension to turn it into a Markdoc page:

How do I set a page title?
By default, the page title is the same as the file name. If you want another title, you can set it in the page frontmatter. The frontmatter is a section, at the top of your page, delimited by three dashes:
---title: My custom page title---Page content...
How do I set a page description?
Similar to the title, the page description is added in the page frontmatter:
---title: My custom page titledescription: My page subtitle---Page content...
How do I add a heading?
In Markdown/Markdoc, headings are added by prepending one or more #
symbols before the text.
# Heading 1## Heading 2### Heading 3
How do I add an image?
Drag the image into the editor, and it will be uploaded to Motif. By default, it will insert a regular Markdown image tag:

If you want more options, such as adding a legend, use the custom img
component:
{% img src="https://res.cloudinary.com/djp21wtxm/image/upload/v1662474675/i834x564-yrzfDVudHfjV_pgj6tc.png" legend="Image description" alt="Alt text" /%}
If you have images hosted elsewhere, simply replace the src
part with their public URLs.
How do I resize an image?
You can resize an image by either using the width
attribute with the supported values 1/4
, 1/3
, 1/2
, 2/3
, 3/4
, as follows:
{% img src="https://res.cloudinary.com/djp21wtxm/image/upload/v1662474675/i834x564-yrzfDVudHfjV_pgj6tc.png" width="1/3" /%}
If you want a more precise value, you can use Tailwind classes via the className
attribute, for instance:
{% img src="https://res.cloudinary.com/djp21wtxm/image/upload/v1662474675/i834x564-yrzfDVudHfjV_pgj6tc.png" className="w-[200px] sm:w-[400px]" /%}
How do I center or right align an image?
You can center an image by setting the center
attribute to true
:
{% img src="https://res.cloudinary.com/djp21wtxm/image/upload/v1662474675/i834x564-yrzfDVudHfjV_pgj6tc.png" size="1/2" center="true" /%}
Similarly, you can right-align an image by setting the right
attribute to true
:
{% img src="https://res.cloudinary.com/djp21wtxm/image/upload/v1662474675/i834x564-yrzfDVudHfjV_pgj6tc.png" size="1/2" right="true" /%}
How do I add a link?
Links have the form [Link label](link-url)
. For external links, simply provide the full URL:
[Motif website](https://motif.land)
For internal links, provide the absolute path to the page instead:
[My page](/link/to/my/page)
The link of an internal page is determined by its name, and the folder it's in. Everything is lowercased, and spaces are replaced with dashes. For instance, if you have a page named Responsive Designs
inside a folder named Layout and Design
, its path will be /layout-and-design/responsive-designs
, and you may link to it as follows:
[Responsive Designs](/layout-and-design/responsive-designs)
How do I add an email link?
Simply prepend mailto:
to the email address, and use the regular link tag, e.g.:
[Contact us](mailto:contact@example.com)
How do I make my text italic or bold?
Italic and bold text are enclosed within one or two asterisks:
Some *italic* and **bold** text.
You may also select some text, and use the shortcuts (italic) and (bold).
How do I add a horizontal separator?
A horizontal separator can be added using three dashes:
Above---Below
How do I add a table?
In Markdoc, tables use the following syntax:
{% table %} * Heading 1 * Heading 2 --- * Row 1 Cell 1 * Row 1 Cell 2 --- * Row 2 Cell 1 * Row 2 cell 2 {% /table %}
How do I add a note?
Notes allow you to highlight content with various levels of prominence, for instance warnings or errors.
{% note %} An info note. {% /note %} {% note type="warning" %} A warning note. {% /note %} {% note type="error" %} An error note. {% /note %}
How do I add a collapsible section?
A collapsible section, such as what you are currently reading, allows you to hide away large amounts of content. It is revealed by clicking on the heading.
{% collapse title="Heading" %} Hidden content. {% /collapse %}
How do I add a tabs block?
A tab block enables you to organize your content in overlapping panels, accessible via a horizontal tab bar.
Tab 1 content.
{% tabs %} {% tab title="Tab 1" %} Tab 1 content. {% /tab %} {% tab title="Tab 2" %} Tab 2 content. {% /tab %} {% tab title="Tab 3" %} Tab 3 content. {% /tab %} {% /tabs %}
How do I publish a page?
Hit the Share button, and toggle on "Public access" for the page. When ready, hit "Publish site".

How do I preview a page before publishing it?
Yes. While working on your site, you may want to see how it looks before publishing it. In the Share menu, you will find a "Preview" URL just for that:

Custom components
In the Markdoc template, some commonly used components have been created to work out of the box. Reach out if you want more.
How do I add a YouTube video?
{% youtube src="YOUR_YOUTUBE_EMBED_URL" /%}
How do I add a Loom video?
{% loom src="YOUR_LOOM_EMBED_URL" /%}
How do I add a Twitter embed?
{% tweet link="YOUR_TWITTER_URL" /%}
How do I add a Typeform?
{% typeform src="YOUR_TYPEFORM_EMBED_URL" /%}
How do I add a Pitch deck?
{% pitch src="YOUR_PITCH_EMBED_URL" /%}
How do I add an Arcade demo?
{% arcade src="YOUR_ARCADE_EMBED_URL" /%}
Configuration
How do I configure the navigation bar links?
The navigation bar is configured in the file named project-config.ts
, at the root of your project source. If you previously switched to the "Pages" view, you will need to switch back to "Source" view to see it in the sidebar. Alternatively, you can jump to the file by hitting and type project-config
.
export default {navbar: {topLinks: [{ title: "Support", href: "/" },// ...],tabs: [{ title: "Home", href: "/" },// ...],},
How do I add an entry to the guides sidebar?
Similar to the navigation bar, the Guides sidebar menu in configured in project-config.ts
, under the sidebar
entry.
export default {// ...sidebars: {guides: [{title: "Getting started",pages: [{title: "Introduction",href: "/guides/getting-started/introduction",},{title: "Installation",href: "/guides/getting-started/installation",},],},// ...]}// ...}
To add a new section or a new page inside an existing section, simply edit the list with the appropriate info.
How do I configure the guides gallery?
Similar to the guides sidebar, the guides gallery is configured under the guidesGallery
entry in project-config.ts
export default {// ...sampleGallery: {Develop: [{title: "Markdoc",// ...},]}}
The top level keys (Develop
, Databases
, Deploy
) define the tab names. Inside each of the entries are the links to the guides, which include a title, a description, a cover image, and the path to the guide itself. You can add as many tabs and entries as you need, and the tab panel will adjust itself accordingly.
How do I change the primary color?
By default, the primary color is sky
. This can be changed in tailwind.config.js
, located at the root of your project. Locate the colors
entry, and change the primary
key to either another predefined color from the Tailwind palette:
colors: {primary: colors.sky,},
or create your own, by specifying each of the variants explicity:
colors: {primary: {50: '#e7fdff',100: '#cffafe',200: '#a5f3fc',300: '#67e8f9',400: '#22d3ee',500: '#06b6d4',600: '#0891b2',700: '#0e7490',800: '#155e75',900: '#164e63',}},