Contributing to the developer portal

# Writing pages

This documentation is built with VuePress 2, running on Vue 3. We recommend you first read the following guides if you're not familiar with VuePress or Vue:

VuePress

• Page
• Markdown

Vue

• Fallthrough Attributes

Tailwind CSS

• Tailwind CSS 3

# Frontmatter

At the start of each .md file, you can add frontmatter. Frontmatter should be valid YAML. Below is described what properties you can use and how it affects the page.

Example:

---
title: My Page
---

## My page content

Hello!

Here is an overview of the most relevant values:

See Frontmatter for all default options.

# Heading levels

A page title should be h2, and content headers start at h3, but we've made it easier by correcting h1 and h2 tags automatically. So you can write your page in any of the following ways:

---
title: Title
---

## Subject 1

## Subject 2

## Title

### Subject 1

### Subject 2

### Title

#### Subject 1

#### Subject 2

They will all be rendered the same way:

<h2>Title</h2>

<h3>Subject 1</h3>

<h3>Subject 2</h3>

# Redirecting

Sometimes a page is not available in all languages, but you do want to show a redirect link to it because people might miss out on useful information otherwise.

Let's assume the following:

• There are multiple languages defined: nl and en
• The default language is en
• We have the following directory structure:

  src
  ├── nl
  │   └── subject
  │       └── my-page.md
  └── subject
      └── my-page.md
  

Now, if src/subject/my-page.md contains the following content:

---
title: My Page
redirect: true
---

This will show something along the lines of the following on the page:

This page is available in the following languages:

- 🇳🇱 (Nederlands)[/nl/subject/my-page.md]

But if the Dutch variant was named mijn-pagina.md instead of my-page.md, this will not work. The automatic resolution checks if the resolved route is present in the array of registered routes, which /nl/subject/my-page.md will not be, if it's actually called /nl/subject/mijn-pagina.md.

In this case, you can manually define which page it should link to in subject/my-page.md:

---
title: My Page
languages:
  nl: subject/mijn-pagina/
---

Now this page will show a redirect link to /nl/subject/mijn-pagina.md.

# Markdown

# Code

Simple inline snippets of code are written between backticks. Like this.

# Code blocks

Write a code block between a fence of three backticks. You can define a language in the first one to provide syntax highlighting.

### This is markdown

I am **bold**, but I am _not_. I am **_both_**

You can also highlight specific lines. See Code blocks for details.

{
  "type": "json",
  "line": "highlighted",
  "this-line": "not highlighted..."
}

# Available components

We've provided some extra components you can use in your markdown content. Their usages are explained below.

# Http

# Props

# Usage

<Http code="204" />

# Result

# DataType

With DataType, you can provide a consistent way of displaying a data type and a link to its source and more information. It supports the following types:

• carrier
• delivery-type
• package-type
• platform
• shipment-status

# Props

# Usage

<DataType
  type="shipment-status"
  id="3" />

<DataType
  type="carrier"
  name="dpd" />

<DataType
  type="package_type"
  name="4" />

# Result

# DataTypeDefinition

# Props

# Usage

<DataTypeDefinition
  pattern="/\d{2}:\d{2}:\d{2}/"
  example="08:00:00" />

# Result

# MPImg

# Props

# Usage

<MPImg
  src="/integrations/chrome.svg"
  class="max-w-xs" />

# Result

# Shield

Renders a shield from shields.io.

# NpmShield

<NpmShield package="@myparcel/sdk" />

# GitHubShield

<GitHubShield repo="myparcelnl/sdk" />

# PackagistShield

<PackagistShield package="myparcelnl/sdk" />

# Containers

Containers are rendered in markdown and are written like this:

::: <name> <attributes>
<content>
:::

Any markdown can go between the fences (:::).

# Alerts

There are a currently two different alerts: note and tip.

# Example

::: note
Note content!
:::

::: tip
Tip content!
:::

::: note With a header
Wow!
:::

# Result

# Expand

The "expand" container can be used to hide content until the user clicks on its header to expand it.

# Example

::: expand
This is collapsed content.
:::

::: expand With a header
Collapsed content with a custom header.

| One | Two | Three  |
| --- | --- | ------ |
| And | a   | table! |

:::

::: expand h6: With a custom tag header
Collapsed content with a header with a custom html tag.
:::

# Result

# Attributes

You can use all classes from Tailwind CSS 3 on any inline component or html tag.

See Fallthrough Attributes for more information on how this works on Vue components.

# Example

<!-- Padding: 5, width: 12, background-color: monstera 500 -->
<MPImg
  alt="Shopware"
  src="/integrations/shopware.svg"
  class="p-3 w-12 bg-monstera-500" />

<!-- Padding: 1, width: 18, margin-left: 3, background-color: goldfish 500 -->
<MPImg
  alt="C#"
  src="/integrations/c-sharp.svg"
  class="p-1 w-18 ml-3 bg-goldfish-500" />

# Theme

We use Tailwind CSS 3 with a few theme modifications.

# Border radius

# Custom colors

These are available for all color utilities, like bg-*,text-*, border-*, etc.

# Min and max width/height

The maxHeight, maxWidth, minHeight and minWidth utilities have been extended to include all spacing values from width and height.

# Editing non-markdown content

# Integrations

Integrations data is located in integrations.json . Edit it there to see the changes reflected on all places where the Integration component is used. Just reference the name, and all other data will be retrieved from that .json file.

<Stack class="lg:grid-cols-4 md:grid-cols-3 grid-cols-2">
  <Integration name="php-sdk" />
  <Integration name="woocommerce" />
  <Integration name="google-chrome-extension" />
</Stack>

PHP SDK

View on GitHubopen in new window

Documentation

WooCommerce

View on GitHubopen in new window

Documentation

Google Chrome Extension

Documentation

# Code

To run the project, check out the repository and run the following commands:

yarn install
yarn translations:import
yarn dev

This installs dependencies, downloads translations and then starts the dev server.