Docs Theme

When writing docs with the base layer adds several components and features that can help you write docs. This page will cover the features and components that are available to you.

Writing Docs

Linking

Since the docs consist of multiple content sources coming from many repositories, it's important to ensure that any links you create include the base path of the docs you're working on.

For example, if you're editing the magento docs (https://docs.alokai.com/integrations/magento), you'll want to make sure that any links you create include the /integrations/magento path.

To make this easier, you can use the $base/ alias at the beginning of your links to automatically include the base path of the docs you're working on.

During local development, the URLs may be different than the production URLs - depending on the base property in your nuxt.config.ts file.

Images

Any images in the content directory will automatically be available in the production build.

They'll keep the same path as they have in the content directory, prefixed by the base path of the docs you're working on.

For example, in the magento docs (with a base URL of integrations/magento if you have an image at content/images/foo.png, it will be available at https://docs.alokai.com/integrations/magento/images/foo.png.

Local Development

To make it easier to work with individual project's documentation, each repository docs folder is a fully functional Nuxt project.

However, the only files that are relevant for the production deployment are the files in the content directory. This means that any custom components, layouts, or other files you create in the docs directory will not be included in the production build.

If you need to add custom components/layouts, they'll need to be added to the Docs Base Layer.

Syntax Highlighting

Like other Markdown syntax, the fenced code-block is marked by ``` and you can specify the language after the first set of backticks.

```js
function test() {
  let x = 'hello world'
  console.log(x)
}
```

function test() {
  let x = 'hello world'
  console.log(x)
}

Line-highlighting

You can highlight specific lines of code by adding a {} after the language name and specifying the line numbers you want to highlight.

You can highlight a single line (e.g. {1}, a range of lines (e.g. {1-3}), or any combination of lines/ranges (e.g. {1,3-5}).

```js{1,3}
function test() {
  let x = 'hello world'
  console.log(x)
}
```

function test() {
  let x = 'hello world'
  console.log(x)
}

Filename

You can add a filename to your code-block by adding a [] after the language name and specifying the filename you want to display.

```ts{1,3}[Foo.ts]
function test() {
  let x = 'hello world'
  console.log(x)
}
```

function test() {
  let x = 'hello world'
  console.log(x)
}

Code Groups

Using the CodeGroup component, you can create a tabbed code group by inserting multiple fenced code blocks into the default slot. The CodeGroup component will automatically create a tab using the file name of each code block

::code-group
```bash[yarn]
yarn add @storefront-ui/vue
```
```bash[npm]
npm i @storefront-ui/vue
```
```bash[pnpm]
pnpm add @storefront-ui/vue
```
::

yarn add @storefront-ui/vue

Lists

If you want to create a feature list, a checkpoint list, or another kind of list, you can use the list component. The list component will automatically format your list items based on the type prop you provide.

Props

• type?: string - the type of list to render. This prop effects the icon/color.
  • Possible values: success, negative
  • Default value: success

Success

::list{type="success"}
- just write a normal list
- and all the formatting will come!
- just like that! This is helpful for things like prequisites, features, etc.
::

Negative

::list{type="negative"}
- just write a normal list
- and all the formatting will come!
- just like that!
::

Steps

To show installation steps, the Steps component can be helpful. The Steps component will automatically number your steps.

You can create as many steps as you want by passing slots. Slots should be named #section-{i} where i is a number that determines the order that your sections will render.

For example, here's a 3 step process describing how to use this component.

::steps
#step-1
### Create a Markdown file

To use the `Steps` content component, you'll need to create a Markdown file. 
You can do this by creating a file with the `.md` extension.

#step-2
### Use the MDC Syntax

You can use the MDC syntax by using `::` followed by the component name. 
Then, we can create slots called `#step-1`, `#step-2`, 
and `#step-3` to create our steps.


#step-3
### Make sure it's working!

Now, we should have a working `Steps` component.
::

Containers

Grid

The grid component can be used to create a responsive grid layout. You can create as many rows as you want by passing slots to the grid component. Each slot will fill a spot in your row-column layout. The grid component will automatically wrap your slots into rows and columns based on the props you provide.

Slots should be named #section-{i} where i is a number that determines the order that your sections will render.

Props

• columns?: number- the maximum number of columns per row
  • Possible values: 2, 3, 4
  • Default value: 2
  • Note: since this is a number, the proper MDC syntax is :columns="2"
• gap?: string - the gap between each column
  • Possible values: xs, sm, md, lg, xl
  • Default value: md

Example

::grid{:columns="2" gap="sm"}
#section-1
**Section 1**

We can use _Markdown syntax_ inside of our MDC components!

#section-2
section 2

#section-3
section 3

#section-4
section 4
::

Card

The card component can be used to create a card with a title and description.

Props

• to?: string - the link to navigate to when the card is clicked
  • Note: if this prop is not provided, the card will not be clickable.
• title?: string - the title of the card
• description?: string - the description of the card
• icon?: string - the icon to display on the left side of the card
  • Under the hood, this links to Nuxt Icon and Iconify. So any icon that is supported by Iconify can be used here. See the full set of Iconify icons

Example

Since all of the card data can be controlled with props, the simplest way to use the card component is using the MDC inline component syntax.

:card{to="/general" title="What is Alokai?" description="New here? Learn about all the different ways Alokai can help you build with performant websites." icon="ri:book-2-fill"}

If the to prop is provided, the card will be rendered as a link. If the icon prop is provided, the icon will be rendered on the left side of the card.

:card{title="What is Alokai?" description="New here? Learn about all the different ways Alokai can help you build with performant websites." }

When combined with the grid component, you can create a grid of cards - which is a great way to display a list of links.

::grid{:columns="2" gap="sm"}
#section-1
:card{to="/general" title="What is Alokai?" description="New here? Learn about all the different ways Alokai can help you build with performant websites." icon="ri:book-2-fill"}

#section-2
:card{to="/contributing/docs/writing-guide" title="Let's learn more!" description="Want to know best practices on writing docs? Click to go back to the our writing guide" icon="ri:pencil-fill"}
::

Callouts

Callouts can be used to highlight important information. There are four types of callouts: tip, warning, info, and danger.

::tip
This will be rendered as a tip.
::

::warning
This will be rendered as a warning.
::

::info
This will be rendered as an info block.
::

::danger
This will be rendered as an danger block.
::

::read-more
This is for backwards-compability with the Vuepress theme, we recommend using the `info` block instead.
::

Each callout block can also have a title

By using the MDC Slot Syntax, you can add a title to each callout block.

::tip
This is the body content

#title
:icon{name="ri:check-fill" class="mr-1"}
Here's some title
::

To help with the migration from Vuepress to Nuxt Content, the title syntax used by Vuepress Custom Containers will also work, but we recommend migrating to the Nuxt Content slot syntax.

Additional Components

There are a couple additional components that might be useful when writing docs.

hr

With MDC syntax, you can create any HTML element by using the :{element} prop. While we suggest that you using this to create things like complex div containers. This can be helpful for adding horizontal-rules.

Example

:hr

icon

The icon component is a wrapper around Nuxt Icon. This can be used to add any icon from the Iconify library.

Props

• name: string - the name of the icon to display
• class?: string - any additional classes to pass to the icon component

:icon{name="ri:hearts-fill" class="text-4xl text-red-500"}

Frontmatter Options

To help customize pages, we've added a few options that you can add to the frontmatter of your Markdown files.

layout

Available options: fullscreen or default

The layout option can be used to change the layout of your page. The fullscreen layout will remove the table of contents from the page. The default layout will automatically take the headers in your page and create a table of contents.

tag

---
tag: Hello
---

If you set the tag property, the value you provide will be added as a tag above the title of the page.

This can be helpful to add statuses (e.g. WIP, Deprecated, Beta, etc.) to your pages or to add a label (e.g. Enterprise, Community, Open Source, etc.).

title

By default, the title of the page - which is available in the meta title and the sidebar - is the first h1 element in the page. If you want to override this, you can set the title property in the frontmatter.

---
title: Custom title
---

Partials

The docs theme also has support for reusable content blocks called partials that can be inserted into several pages.

To create partials, you need to add a _partials folder into the content folder and then you can create any markdown files you need in here.

Then, you can use the Partial component, pass your filename as the content prop, and then the contents of that file will be injected into whatever page you need.

For example, if we had a requirements.md file in our _partials folder, we can use it like this.

::partial{content=requirements}
::

Currently, the partials must be in the same content repo that they are being used meaning that no cross repo partials can exist. The main reason for this is that if we allow cross-repo partials, they won't be working out-of-the-box in local development for a repo's docs.