Directives

Directives are what makes Marque unique. They allow you to create custom elements, layouts and interactive components using simple markdown syntax.

Block directives

Block directives have an opening tag that starts with @name and a closing tag that ends with @end name. The content between these tags is the directive's children, which can be other directives or markdown content.

PreviewSyntax

Title

I'm inside a card directive, which is a block directive.

@card 
  ##* Title
  I'm inside a card directive, which is a block directive.
@end card

Inline directives

Inline directives do not require a closing tag and can be used within a line of text. They are useful for adding small elements or styling within a line of markdown content.

PreviewSyntax

Here's an inline directive:

There's now a divider between the title and me!

##* Here's an inline directive: @sparkle
@divider 

There's now a divider between the title and me!

Use the summary on the right to quickly navigate to the directive you want to learn about, or keep reading for a full list of built-in directives.

Block directives

`@callout`

parameter	description
type	block directive
path	`directives/builtins.js`
description	colored block used to highlight information
`.info`	blue informational (default)
`.warn`	yellow warning
`.danger`	red danger
`.ok`	green success

PreviewSyntax

You can get the blue callout by using the .info modifier or leaving it empty.

Watch out for this.

This is dangerous!

Luigi time!

@callout
You can get the blue callout by using the `.info` modifier or leaving it empty.
@end callout

@callout .warn
Watch out for this.
@end callout

@callout .danger
This is dangerous!
@end callout

@callout .ok
Luigi time!
@end callout

`@card`

parameter	description
type	block directive
path	`directives/builtins.js`
description	standard content container with a border and padding
`.left`	left-align content (default)
`.center`	center-align content
`.right`	right-align content
`.primary`	primary color variant
`.secondary`	secondary color variant
`.tertiary`	tertiary color variant
`.dark`	dark mode variant

PreviewSyntax

Spooky

Join the dark side.

Centered title

Content goes here.

@card .dark
##* Spooky
Join the dark side.
@end card

@card .center .tertiary
##* Centered title
Content goes here.
@end card

`@demo`

parameter	description
type	block directive
path	`directives/demo.js`
description	shows a live preview with a toggleable syntax pane
`"label"`	optional caption shown in the demo header
`.code`	open the code tab by default

PreviewSyntax

Demo title

Recursion is fun!

Switch between preview and syntax.

@card .secondary
##* Recursion is fun!
@divider
Switch between preview and syntax.
@end card

@demo .code "Demo title"
@card .secondary
##* Recursion is fun!
@divider
Switch between preview and syntax.
@end card
@end demo

`@dropdown`

parameter	description
type	block directive
path	`directives/dropdown.js`
description	collapsible block that can be toggled open and closed. Starts in `closed` state by default.
`.open` `.expanded` `.default-open`	create the dropdown in the open state
`.disable-cache`	disables the caching behaviour
note	the `@dropdown` directive has built-in caching, and remembers its open/closed state, unless disabled

PreviewSyntax

@dropdown .open "Open by default"
You can see me!
@end dropdown

@dropdown "Closed by default"
And now you see me!
@end dropdown

@dropdown .open .disable-cache "Close me!"
Close me and refresh the page. I won't remember that you closed me. You can't get rid of me >:)
@end dropdown

`@hero`

parameter	description
type	block directive
path	`directives/builtins.js`
description	prominent `<section>` wrapper, modifiers are mapped to CSS classes
`.center`	center-align content

PreviewSyntax

I'm a Hero!!!

And I'm a Robin?

@hero .center
#* I'm a Hero!!!
And I'm a Robin?
@end hero

`@product-card`

parameter	description
type	block directive
path	`directives/product-card.js`
description	renders a `<product-card>` custom element
`.featured`	applies featured border styling via the `variant` attribute
`label`	becomes the `title` attribute on the element

PreviewSyntax

Fast setup

Copy the starter and change the theme later.

@product-card .featured Starter
##* Fast setup
Copy the starter and change the theme later.
@end product-card

`@row`

parameter	description
type	block directive
path	`directives/builtins.js`
description	responsive grid whose columns are sized by the number of block directive children
note	warns at build time if it has no block directive children

PreviewSyntax

🡸 I'm on the left!

I'm on the right. 🡺

@row
  @card
    🡸 I'm on the left!
  @end card
  @card .right
    I'm on the right. 🡺
  @end card
@end row

The content in a row is responsive, so on smaller screens the columns may stack vertically instead of horizontally.

`@section`

parameter	description
type	block directive
path	`directives/builtins.js`
description	renders a `<section>` wrapper, modifiers are mapped to CSS classes

PreviewSyntax

Welcome

Content inside a section.

@section .highlight
##* Welcome
Content inside a section.
@end section

`@stat`

parameter	description
type	block directive
path	`directives/builtins.js`
description	value and label pair, extracted from the first `##` and `p` in the rendered children

PreviewSyntax

87%

Of statistics are made up on the spot.

@stat
## 87%
Of statistics are made up on the spot.
@end stat

`@step`

parameter	description
type	block directive
path	`directives/builtins.js`
description	numbered process item, auto-increments within its scope
`n`	force this step to display a specific number
`*`	show `*` instead of a number
`reset:n`	reset the counter to `n` at this point
note	each block scope keeps its own step sequence

PreviewSyntax

Go to the Marque repo on GitHub.
Open Marque GitHub

Star the repo.

Profit ???

@step
Go to the Marque repo on GitHub.
@[Open Marque GitHub](https://github.com/Loxed/marque){.primary}
@end step

@step
Star the repo. @sparkle
@end step

@step *
Profit ???
@end step

`@tab`

parameter	description
type	block directive
path	`directives/tab.js`
description	a labelled tab panel; consecutive `@tab` blocks are automatically grouped into a tab strip
`label`	visible tab button text written after the directive name

PreviewSyntax

Install via winget:

winget install marque

Install via Homebrew:

brew install marque

Install via npm:

npm install -g marque

@tab Windows
Install via **winget**:

```
winget install marque
```
@end tab

@tab macOS
Install via **Homebrew**:

```
brew install marque
```
@end tab

@tab Linux
Install via **npm**:

```
npm install -g marque
```
@end tab

Tabs work inside any parent directive: @card, @section, bare page, etc. Groups are broken automatically by any non-@tab element in-between them.

`@actions`

See @button for how to create buttons using Marque.

parameter	description
type	block directive
path	`directives/actions.js`
description	responsive flex group for buttons or other compact actions
`.center`	center the actions horizontally
`.right`	align the actions to the right
`.stack`	stack actions vertically

PreviewSyntax

Quickstart Read the docs

@actions .center
@[Quickstart](/quickstart.mq){.primary}
@[Read the docs](/docs.mq)
@end actions

`@filetree`

parameter	description
type	block directive
path	`directives/filetree.js`
description	renders a code-themed directory tree from simple text lines
syntax	write the root on the first line, then use `-`, `--`, `---` for each nesting level

PreviewSyntax

Structure

my-site/
- folder/
- file.mq

Nested example

temp/
- subtemp/
  - subsubfile

@filetree "Structure"
my-site/
- folder/
- file.mq
@end filetree

@filetree "Nested example"
temp/
- subtemp/
-- subsubfile
@end filetree

`@link-card`

parameter	description
type	block directive
path	`directives/link-card.js`
description	turns a card into one big clickable link
`target`	page path or URL written after the directive name
`.primary` `.secondary` `.tertiary`	optional card tone modifiers
note	avoid placing other links or buttons inside a link-card

PreviewSyntax

CLI Commands

Reference every Marque command in one place.

@link-card .primary /docs/cli.mq
##* CLI Commands
@divider
Reference every Marque command in one place.
@end link-card

Inline directives

`@badge`

parameter	description
type	inline directive
path	`directives/badge.js`
description	small pill label rendered inline within text or headings
`label`	badge text written after the directive name
`.info`	blue (default)
`.ok`	green
`.warn`	yellow
`.danger`	red
`.primary` `.secondary` `.tertiary`	theme colour variants

PreviewSyntax

Marque v1.0 is out now!

New Stable Deprecated Breaking changes

Content
Under the badge

Marque @badge "v1.0" is out now!

@badge .info "New" @badge .ok "Stable" @badge .warn "Deprecated" @badge .danger "Breaking changes"

@badge .primary "Content"
@badge Under the badge

`@button`

Buttons don't use the @button directive; they are written using the markdown link syntax: @[label](url)

`@[label](url)`

parameter	description
type	special inline syntax
path	`src/renderer.js`
description	renders a styled link button as `<a class="mq-btn">...</a>`
`label`	visible button text inside `[...]`
`url`	link target inside `(...)`
`.primary` `.secondary` `.tertiary`	built-in button variant classes
`.class`	optional extra CSS classes inside `{...}`

PreviewSyntax

Quickstart Read the docs
Open migration guide

Normal link Action button Another action

@[Quickstart](../quickstart.mq){.primary} @[Read the docs](../docs.mq)
@[Open migration guide](../migration.mq){.secondary}

@actions .center
[Normal link](/)
@[Action button](#){.tertiary}
@[Another action](#)
@end actions

`@divider`

parameter	description
type	inline directive
path	`directives/builtins.js`
description	renders a horizontal divider line

PreviewSyntax

Section title

Content below the divider.

##* Section title
@divider
Content below the divider.

`@kbd`

parameter	description
type	inline directive
path	`directives/kbd.js`
description	renders keyboard shortcut key caps, with automatic platform-aware symbol swapping
`keys`	key combo written after the directive name, separated by `+`
`.mac`	always render using Mac symbols (`Ctrl/Cmd` → `⌘`, `Alt/Option` → `⌥`)
`.win`	always render using Windows labels, regardless of platform
note	on mobile devices, key caps are replaced with inline code styling
aliases	`Ctrl` / `Cmd` / `Command` are treated as the same primary shortcut key, and `Alt` / `Option` are treated as the same alternate key

PreviewSyntax

In Marque, press CtrlK to open the search menu.

Mac users use ⌘⇧3 to take a full page screenshot and ⌘⇧4 to capture a specific portion of the screen.

For some reason CtrlAltShiftWinL opens LinkedIn on Windows. Don't ask me why.

In Marque, press @kbd Ctrl+K to open the search menu.

Mac users use @kbd .mac Ctrl+Shift+3 to take a full page screenshot and @kbd .mac "Cmd+Shift+4" to capture a specific portion of the screen.

For some reason @kbd .win "Ctrl+Alt+Shift+Win+L" opens LinkedIn on Windows. Don't ask me why.

You can write either Ctrl or Cmd for the primary shortcut key, and either Alt or Option for the alternate key. Marque normalizes them and still applies the same automatic OS swap (⌘, ⌥, ⇧) plus .mac / .win overrides.

`@sparkle`

parameter	description
type	inline directive
path	`directives/sparkle.js`
description	animated decorative star rendered in the primary colour

PreviewSyntax

Inline sparkle looks like this and keeps flowing with the text.

Inline sparkle looks like this @sparkle and keeps flowing with the text.

`@spotlight`

Spotlight is a directive purely meant for the mida theme and works using that theme only. It will not make sense to use it outside of that context. Switch this page's theme to mida to see it in action!

parameter	description
type	inline directive
path	`directives/spotlight.js`
description	decorative block

PreviewSyntax

@spotlight

Directives

What is a directive?

Why directives?

How do I use directives?

Block directives

Title

Inline directives

Here's an inline directive: ✶

Use the summary on the right to quickly navigate to the directive you want to learn about, or keep reading for a full list of built-in directives.

Block directives

@callout

@card

Spooky

Centered title

@demo

Recursion is fun!

@dropdown

@hero

I'm a Hero!!!

@product-card

Fast setup

@row

@section

Welcome

@stat

@step

@tab

@actions

@filetree

@link-card

CLI Commands

Inline directives

@badge

@button

@[label](url)

@divider

Section title

@kbd

@sparkle

@spotlight

Here's an inline directive:

`@callout`

`@card`

`@demo`

`@dropdown`

`@hero`

`@product-card`

`@row`

`@section`

`@stat`

`@step`

`@tab`

`@actions`

`@filetree`

`@link-card`

`@badge`

`@button`

`@[label](url)`

`@divider`

`@kbd`

`@sparkle`

`@spotlight`