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 resolution by type
| 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 |
Document links (sidebar and body)
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/pageCommon 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.
 → current page's directory
 → current page's directory
 → doc root
 → traverses up from current dir (works)Image attributes via title string:
:size=WIDTHor:size=WIDTHxHEIGHTor:size=PERCENT%:no-zoom— disable select-to-zoom:class=classnameand: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  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: -->

<!-- ❌ Breaks when embedded from a different directory: -->
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.
Download / asset links
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=.
External links
Any URL containing :// or // is treated as external. Opens in _blank with rel="noopener" by default. Override with :target=_self in title attribute.
Sidebar (_sidebar.md) rules
- All links resolve from doc root, not from the sidebar file’s directory — even nested
_sidebar.mdfiles. - Unique links required — duplicate resolved hrefs cause multiple active highlights.
- Only files in
_sidebar.mdare indexed by search. - Files NOT in the sidebar are still accessible via direct URL.
Sidebar structure syntax
- **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)
.mdextension optional (stripped automatically)
Sidebar file discovery
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:
- Publishing time scales with entire repo size, not subfolder.
- Risk of exceeding 2 GB limit.
- Any change in any subfolder re-triggers ALL docs in that repo.
Validate your links
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 docsThe 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.