A Singapore Government Agency Website

Platform rules

The Documentation Portal uses a custom Docsify fork (@developerportalsg/docsify@4.12.18) with custom link renderers. Link resolution differs from standard markdown — understanding these rules prevents broken links on the portal.

Link type Resolves from ../ works /path means
Sidebar links Doc root No Doc root
Document links (body) Doc root No Doc root
Images Current page directory Yes Doc root
Embedded (:include) Current file directory Yes BROKEN
Downloads/assets Mixed (see below) Yes Doc root
Anchors (#heading) Current page N/A N/A

All document links resolve from the repository root (relative to basePath), regardless of which file contains the link.

<!-- From ANY file at ANY depth, these all resolve identically: -->
[Link](page)           → /docs/{slug}/page
[Link](page.md)        → /docs/{slug}/page         (.md stripped)
[Link](./page)         → /docs/{slug}/page         (./ stripped)
[Link](/page)          → /docs/{slug}/page          (/ = doc root)
[Link](folder/page)    → /docs/{slug}/folder/page

Common mistake: From level1/README.md, writing [Link](other-page) resolves to /docs/{slug}/other-page, NOT /docs/{slug}/level1/other-page. To link to a sibling file, write the full path: [Link](level1/other-page).

../ is NOT supported in document links. The renderer passes it through raw, and the browser resolves /docs/{slug}/../path to /docs/path — outside your document.

Images

Images resolve from the current page’s directory, unlike document links.

![](image.png)              → current page's directory
![](./image.png)            → current page's directory
![](/images/image.png)      → doc root
![](../../images/image.png) → traverses up from current dir (works)

Image attributes via title string:

  • :size=WIDTH or :size=WIDTHxHEIGHT or :size=PERCENT%
  • :no-zoom — disable select-to-zoom
  • :class=classname and :id=idname

Embedded files (:include)

Embeds resolve from the current file’s directory. Absolute paths (/path) are broken for embeds.

[x](file.md ':include')           → relative to current file ✓
[x](../file.md ':include')        → traversal works ✓
[x](/file.md ':include')          → BROKEN — prepends parent path ✗

Only .md files can be embedded. The :include directive must be in the title: ':include'.

Embed image conflict

Images inside embedded content resolve from the viewing page’s directory, not the snippet file’s directory.

A relative image ![](assets/logo.png) in shared/intro.md resolves to shared/assets/logo.png when viewing the snippet directly. But when the snippet is embedded in README.md (at root), the same image resolves to assets/logo.png at root — a different file or missing entirely.

Correct pattern for images in snippets: Use root-relative paths.

<!-- ✅ Works everywhere — in snippet standalone AND when embedded: -->
![logo](/shared/assets/logo.png)

<!-- ❌ Breaks when embedded from a different directory: -->
![logo](assets/logo.png)

Do not use a file as both a :include snippet and a sidebar-navigable page. If a file is embedded in other pages, it should not appear in _sidebar.md — the relative image paths cannot satisfy both contexts.

Files with recognised extensions (pdf, zip, xls, etc.) follow mixed resolution:

Syntax Resolution
path/file.pdf or /path/file.pdf Root-relative
./path/file.pdf Current-directory-relative
../../path/file.pdf Traversal from current directory

Bare path/file.pdf (no prefix) is root-relative — the opposite of standard filesystem convention.

Anchors

[text](#heading)            → same page anchor (converted to ?id=heading in history mode)
[text](page#heading)        → cross-page anchor (# → ?id= by plugin)
[text](page?id=heading)     → explicit format (also works)

In history mode, # in internal links is automatically converted to ?id=.

Any URL containing :// or // is treated as external. Opens in _blank with rel="noopener" by default. Override with :target=_self in title attribute.

  1. All links resolve from doc root, not from the sidebar file’s directory — even nested _sidebar.md files.
  2. Unique links required — duplicate resolved hrefs cause multiple active highlights.
  3. Only files in _sidebar.md are indexed by search.
  4. Files NOT in the sidebar are still accessible via direct URL.
- **Section Header**

  - [Page Title](path/to/page)
  - [Another Page](path/to/another)
  - Folder Name
    - [Nested Page](folder/nested-page)
  • Plain text = non-clickable section header
  • - [Title](path) = clickable page link
  • Nesting via indentation (2 or 4 spaces)
  • .md extension optional (stripped automatically)

Docsify uses nearest-ancestor lookup: for /level1/level2/page, it checks level1/level2/_sidebar.md → level1/_sidebar.md → _sidebar.md.

Content features

Feature Syntax Notes
Info callout ?> text Blue highlight box
Warning callout !> text Yellow warning box
Mermaid diagrams ```mermaid code block Flowcharts, sequence, Gantt, state, pie
Tabs <!-- tabs:start --> / <!-- tab:Title --> / <!-- tabs:end --> docsify-tabs plugin
Accordion <details><summary>Title</summary>Content</details> SGDS accordion optional
Code highlighting ```lang aspnet, bash, csharp, java, markdown, python, ruby, yaml
Image zoom Default on all images Disable with :no-zoom
Copy code button Auto on all code blocks docsify-copy-code
ToC ignore heading <!-- {docsify-ignore} --> after heading Hides from right-hand ToC
ToC ignore all <!-- {docsify-ignore-all} --> anywhere on page Hides all headings from ToC

Forbidden

What Why
<form> tags Stripped by DOMPurify
../ in document/sidebar links Not resolved by custom renderer
/path in :include embeds Broken — prepends parent path
Snippet as sidebar page Files used as :include must not appear in _sidebar.md — image paths break
Custom docsify plugins Only platform plugins available
Hash-mode URLs (#/path) Auto-redirected to history mode

Platform constraints

Constraint Limit
Max repository size 2 GB
Max files per directory 3,500
Display name Must be unique across entire site
URL slug Derived from display name
basePath depth Max 2 directory levels
Published branch Configurable per document
Git providers GitHub and GitLab (SHIP-HATS)

Multi-doc repo warning

Avoid publishing multiple documents from one repository:

  1. Publishing time scales with entire repo size, not subfolder.
  2. Risk of exceeding 2 GB limit.
  3. Any change in any subfolder re-triggers ALL docs in that repo.

Run the link checker CLI to validate all links against these rules before publishing:

npx @developerportalsg/docportal-cli check-links .
npx @developerportalsg/docportal-cli check-links . --base-path docs

The tool checks document links, sidebar links, image paths, embed paths, and flags ../ and /path violations. Use --json for CI-friendly output.

External resource restrictions

Only https://app.supademo.com is currently supported for external script/style sources beyond the platform’s own resources.

Chat with me!
Bot Launcher