Star on GitHub Create Issues Buy me a Bubble Tea

Timeline

About 1727 wordsAbout 6 min

2025-10-08

Overview

In markdown, use the ::: timeline container with markdown unordered list syntax to achieve timeline rendering effects.

Supports horizontal and vertical orientations
Vertical orientation supports left alignment, right alignment, and justified alignment
Supports icons and line styles
Supports setting colors through preset types, and supports custom colors

This feature is disabled by default. You need to enable it in the theme configuration.

.vuepress/config.ts
export default defineUserConfig({
  theme: plumeTheme({
    markdown: {
      timeline: true, 
    }
  })
})

Syntax

Inside the ::: timeline container, use markdown unordered list syntax. Each list item represents a point on the timeline.

timeline.md
::: timeline Configuration
- Title
  Configuration

  Content

- Title
  Configuration

  Content
:::

For each list item:

Everything from the first line to the first empty line is considered the title. The line immediately following the title is used to configure the behavior of the current item.
After the first empty line: Content

Please ensure correct indentation

A simple example:

Input:

::: timeline
- Node 1
  time=2025-03-20 type=success

  Content

- Node 2
  time=2025-02-21 type=warning

  Content

- Node 3
  time=2025-01-22 type=danger

  Content
:::

Output:

Node 1

Content

2025-03-20

Node 2

Content

2025-02-21

Node 3

Content

2025-01-22

Timeline defaults to vertical orientation

Configuration

Timeline supports highly flexible configuration options, divided into two main parts:

Container Configuration: Configuration on the ::: timeline container, placed after ::: timeline. For example:
::: timeline horizontal renders a horizontally oriented timeline.

List Item Configuration: Configuration for each list item, placed on a separate line immediately following the title. For example:

::: timeline
- Title                          <!--Title line-->
  Also title                     <!--Title line-->
  time=2025-03-20 type=success  <!--Configuration line (optional)-->
                                <!--Empty line (required if content exists)-->
  Content
:::

Container Configuration

Name:horizontal

Optional

boolean

Renders a horizontally oriented timeline.

Name:card

Optional

boolean

Renders each timeline node as a card by default (can be overridden in list item configuration).

Name:placement

Optional

'left' | 'right' | 'between'

Default:'left'

Alignment of timeline nodes. Only effective in vertical orientation

left: Left-aligns the timeline axis
right: Right-aligns the timeline axis
between: Justifies the timeline axis (positions defined by placement in list item configuration, defaults to left)

Name:line

Optional

'solid' | 'dashed' | 'dotted'

Default:'solid'

Line style (can be overridden in list item configuration).

List Item Configuration

Name:time

Optional

string

Default:''

Time point, can be any string such as 2025-03-20, Q1, etc.

Name:type

Optional

Default:'info'

Type of the timeline node.

Name:card

Optional

boolean

Renders the current timeline node as a card. Default value is inherited from container configuration card.

Name:line

Optional

'solid' | 'dashed' | 'dotted'

Default:'solid'

Line style. Default value is inherited from container configuration line.

Name:icon

Optional

string

Default:''

Icon for the timeline node. Supports all iconify icons.

Name:placement

Optional

'left' | 'right' | 'between'

Default:'left'

Defines the position of the current timeline node when container configuration placement is between.

left: On the left side of the timeline axis
right: On the right side of the timeline axis

Name:color

Optional

string

Default:''

Line color for the timeline node. Can be any valid color value.

Examples

Horizontal Orientation

Add horizontal after :::timeline to render the timeline in horizontal orientation.

Input:

::: timeline horizontal
- Node 1
  time=2025-03-20

  Content

- Node 2
  time=2025-04-20 type=success

  Content

- Node 3
  time=2025-01-22 type=danger

  Content

- Node 4
  time=2025-01-22 type=important

  Content
:::

Output:

Node 1

Content

2025-03-20

Node 2

Content

2025-04-20

Node 3

Content

2025-01-22

Node 4

Content

2025-01-22

Right Alignment

Add placement="right" after :::timeline to render the timeline with right alignment.

Input:

::: timeline placement="right"
- Node 1
  time=2025-03-20

  Content

- Node 2
  time=2025-04-20 type=success

  Content

- Node 3
  time=2025-01-22 type=danger

  Content

- Node 4
  time=2025-01-22 type=important

  Content
:::

Output:

Node 1

Content

2025-03-20

Node 2

Content

2025-04-20

Node 3

Content

2025-01-22

Node 4

Content

2025-01-22

Justified Alignment

Add placement="between" after :::timeline to render the timeline with justified alignment.

List items default to the left side of the timeline. Use placement="right" in list item configuration to set right-side position.

Input:

::: timeline placement="between"
- Node 1
  time=2025-03-20 placement=right

  Content

- Node 2
  time=2025-04-20 type=success

  Content

- Node 3
  time=2025-01-22 type=danger placement=right

  Content

- Node 4
  time=2025-01-22 type=important

  Content
:::

Output:

Node 1

Content

2025-03-20

Node 2

Content

2025-04-20

Node 3

Content

2025-01-22

Node 4

Content

2025-01-22

Node Types

Add type=node-type in list item configuration to set the node type for the current item.

Input:

::: timeline
- Node 1
  time=2025-03-20 type=success

  Content

- Node 2
  time=2025-04-20 type=warning

  Content

- Node 3
  time=2025-01-22 type=danger

  Content

- Node 4
  time=2025-01-22 type=important

  Content
:::

Output:

Node 1

Content

2025-03-20

Node 2

Content

2025-04-20

Node 3

Content

2025-01-22

Node 4

Content

2025-01-22

Line Styles

Add line=line-style in container configuration to set the default line style for all nodes.
Add line=line-style in list item configuration to set the line style for a specific node.

Input:

::: timeline line="dotted"
- Node 1
  time=2025-03-20

  Content

- Node 2
  time=2025-04-20 type=success

  Content

- Node 3
  time=2025-01-22 type=danger line=dashed

  Content

- Node 4
  time=2025-01-22 type=important line=solid

  Content
:::

Output:

Node 1

Content

2025-03-20

Node 2

Content

2025-04-20

Node 3

Content

2025-01-22

Node 4

Content

2025-01-22

Nodes with Icons

Add icon=icon-name in list item configuration to add an icon to the node.

Icon names support all iconify icon names.

Input:

::: timeline placement="between"
- Node 1
  time=2025-03-20 placement=right icon=mdi:balloon

  Content

- Node 2
  time=2025-04-20 type=success icon=mdi:bookmark

  Content

- Node 3
  time=2025-01-22 type=danger placement=right icon=mdi:bullhorn-variant-outline

  Content

- Node 4
  time=2025-01-22 type=important card=true icon="mdi:cake-variant-outline"

  Content
:::

Output:

Node 1

Content

2025-03-20

Node 2

Content

2025-04-20

Node 3

Content

2025-01-22

Node 4

Content

2025-01-22

Card Nodes

Card nodes can be flexibly controlled:

Add card in container configuration to make every list item a card node.
Add card=true in list item configuration to set the node as a card node.
Add card=false in list item configuration to set the node as a non-card node.

Card node styles are affected by the type configuration.

Adding card=true / card=false in list item configuration can override the container's card configuration

Input:

::: timeline card
- Node 1
  time=2025-03-20

  Content

- Node 2
  time=2025-04-20 type=success card=false

  Content

- Node 3
  time=2025-01-22 type=danger

  Content

- Node 4
  time=2025-01-22 type=important

  Content
:::

Output:

Node 1

Content

2025-03-20

Node 2

Content

2025-04-20

Node 3

Content

2025-01-22

Node 4

Content

2025-01-22

Custom Node Types

Timeline node types are controlled through CSS Variables. The theme provides the following CSS variables:

:root {
  --vp-timeline-c-line: var(--vp-c-border);   /* Line color */
  --vp-timeline-c-point: var(--vp-c-border);  /* Point color */
  --vp-timeline-c-title: var(--vp-c-text-1);  /* Title text color */
  --vp-timeline-c-text: var(--vp-c-text-1);   /* Content text color */
  --vp-timeline-c-time: var(--vp-c-text-3);   /* Time text color */
  --vp-timeline-c-icon: var(--vp-c-bg);       /* Icon color */
  --vp-timeline-bg-card: var(--vp-c-bg-soft); /* Background color for card nodes */
}

For example, the built-in node type tip:

.vp-timeline-item.tip {
  --vp-timeline-c-line: var(--vp-c-tip-1);
  --vp-timeline-c-point: var(--vp-c-tip-1);
  --vp-timeline-bg-card: var(--vp-c-tip-soft);
}

You can override built-in types or add new types in Custom Styles.

Example:

.vuepress/styles/index.css
.vp-timeline-item.your-type {
  --vp-timeline-c-line: #3cf;
  --vp-timeline-c-point: #3cf;
  --vp-timeline-bg-card: rgba(60, 252, 255, 0.314);
}

::: timeline
- Node 1
  time=2025-03-20

  Content

- Node 2
  time=2025-04-20 type=your-type card=true

  Content

- Node 3
  time=2025-01-22 type=danger

  Content
:::

Node 1

Content

2025-03-20

Node 2

Content

2025-04-20

Node 3

Content

2025-01-22

Contributors

zhenghaoyang24

pengzhanbo

Changelog

10/13/26, 3:56 PM

View All Changelog

e4dae-docs: improve docs (#1071)on 10/13/26
7a454-feat(plugin-md-power): drop optional tag in field container (#987)on 9/12/26
1d04d-feat: add builtin auto-import-components (#932)on 9/9/26
16c2d-docs: update field containeron 6/8/26
38505-docs: update en docs (#708)on 10/9/25
4d236-feat(theme)!: add collections support (#704)on 10/7/25
9f99a-docs: add en markdown doc (#538)on 3/27/25

Collection

markdown

code block

code repl

charts

resource embedded

Custom Homepage

Timeline

Overview

Syntax

Configuration

Container Configuration

List Item Configuration

Examples

Horizontal Orientation

Right Alignment

Justified Alignment

Node Types

Line Styles

Nodes with Icons

Card Nodes

Custom Node Types

Contributors

Changelog