Markdown

The Markdown property is used to display Markdown content within an entity in Port.
Using this property will automatically create an additional tab in each entity page, displaying the formatted content.

An example can be seen in the live demo:
The service blueprint has a README property that displays the service's Readme file. As you can see in the example, the "Payment" service has a README tab that displays the value of the property in markdown format.

Schema definition

{
  "title": "Markdown Property",
  "type": "string",
  "format": "markdown",
  "description": "A Markdown property"
}

Upload images

You can add images directly to your content while editing a markdown property in Port.

Use any of the following methods to upload an image:

• Paste from clipboard: copy an image and paste it into the editor with Cmd+V (macOS) or Ctrl+V (Windows/Linux).
• Drag & drop: drag an image file from your computer into the editor.
• Toolbar: click the image button in the editor toolbar to select a file to upload.

To insert an image hosted at an external URL, use Ctrl+K and provide the image URL.

Limitations:

• Maximum file size: 10MB per image.
• Maximum 50 uploaded images per markdown property.

Limitations

Relative links are not supported

When displaying markdown content in Port (especially content ingested from Git repositories or other external sources), relative links will not work. This is because the markdown is rendered in the context of your Port portal, not the original source location.

For example, links like [guide](./docs/guide.md) or [readme](../README.md) from a GitHub README file will not function correctly when displayed in Port.

Solutions:

• Use absolute URLs instead: [guide](https://github.com/your-org/your-repo/blob/main/docs/guide.md).
• Transform relative links to absolute URLs during ingestion using JQ expressions in your integration mapping.
• For links to other entities in your Port catalog, use entity page URLs: /serviceEntity?identifier=my-service.

GitOps and external markdown files

When using GitOps to display an external markdown file using the markdown property, changes made to the markdown file will not be reflected in Port until the port.yml file is also updated (this triggers a re-ingestion of the entity).

One way to handle this is to add a step in your CI workflow that bumps a "version" field in the port.yml file whenever specific files in the repository are updated, ensuring re-ingestion of the entity.

---

Mermaid

The markdown widget also supports Mermaid, a diagramming and charting tool that uses text and code to generate diagrams and charts.

To use Mermaid with the markdown widget, all you need to do is add mermaid syntax to the markdown property. You can refer to the Mermaid Examples for more examples and information on how to use it.

Mermaid diagram example (click to expand)

```mermaid
sequenceDiagram
    participant ClientService
    participant PaymentService
    participant InventoryService
    participant ShippingService

    ClientService->>PaymentService: Request Payment
    PaymentService-->>InventoryService: Update Inventory
    InventoryService-->>ShippingService: Ship Order
    ShippingService-->>InventoryService: Confirm Shipment
    InventoryService-->>PaymentService: Update Payment Status
    PaymentService-->>ClientService: Return Payment Status

```