shipyard enhances standard markdown with features like admonitions, code block enhancements, tabs, and more. These features work automatically in all documentation and blog content — no additional configuration is needed.
Admonitions (also called callouts) highlight important information with colored boxes. shipyard supports five types using the ::: container directive syntax.
:::note
This is a note. Use it for general information.
:::
:::tip
This is a tip. Use it for helpful advice.
:::
:::info
This is info. Use it for supplementary information.
:::
:::warning
This is a warning. Use it when users should be careful.
:::
:::danger
This is a danger notice. Use it for critical warnings.
:::Add a custom title in square brackets after the type:
:::note[Did you know?]
You can customize the title of any admonition.
:::
:::warning[Security Notice]
Always validate user input before processing.
:::| Type | Color | Default Title | Use Case |
|---|---|---|---|
note | Blue | Note | General information |
tip | Green | Tip | Helpful advice |
info | Cyan | Info | Supplementary details |
warning | Yellow | Warning | Caution or potential issues |
danger | Red | Danger | Critical warnings |
Admonitions follow DaisyUI’s semantic color system, so they automatically adapt to your site’s theme.
shipyard enhances code blocks with titles, line numbers, line highlighting, and magic comments.
Standard fenced code blocks include syntax highlighting via Shiki:
```javascript
function greet(name) {
console.log(`Hello, ${name}!`)
}
```Add a title attribute to display a filename or description above the code block:
```javascript title="src/utils/greet.js"
export function greet(name) {
console.log(`Hello, ${name}!`)
}
```Add showLineNumbers to display line numbers:
```javascript showLineNumbers
function calculateSum(numbers) {
let sum = 0
for (const num of numbers) {
sum += num
}
return sum
}
```Start from a specific line number:
```javascript showLineNumbers=10
const config = {
theme: 'dark',
language: 'en',
}
```Highlight specific lines using curly brace syntax in the code fence:
```javascript {2,4-6}
function processData(data) {
const validated = validate(data) // highlighted
const transformed = transform(validated)
return { // lines 4-6 highlighted
success: true,
data: transformed,
}
}
```Use special comments to highlight lines without the comment appearing in the output:
```javascript
function handleRequest(req, res) {
// highlight-next-line
const userId = req.params.id
// highlight-start
const user = await db.findUser(userId)
if (!user) {
return res.status(404).json({ error: 'Not found' })
}
// highlight-end
res.json(user)
}
```Supported comment syntaxes:
| Language | Single line | Block start | Block end |
|---|---|---|---|
| JavaScript/TypeScript | // highlight-next-line | // highlight-start | // highlight-end |
| Python | # highlight-next-line | # highlight-start | # highlight-end |
| Bash/Shell | # highlight-next-line | # highlight-start | # highlight-end |
| HTML | <!-- highlight-next-line --> | <!-- highlight-start --> | <!-- highlight-end --> |
Combine titles, line numbers, and highlighting in a single code block:
```typescript title="src/api/users.ts" showLineNumbers {3,7-9}
import { db } from './database'
export async function getUser(id: string) {
const user = await db.users.findUnique({
where: { id },
})
if (!user) {
throw new NotFoundError('User not found')
}
return user
}
```Code blocks with the npm2yarn meta string automatically show tabs for npm, yarn, and pnpm:
```bash npm2yarn
npm install @levino/shipyard-base
```This renders a tabbed code block where users can switch between package managers.
The Tabs and TabItem components let you group content into switchable tabs. Import them in MDX files:
import { Tabs, TabItem } from '@levino/shipyard-base/components'
<Tabs items={['npm', 'yarn', 'pnpm']}>
<TabItem value="npm">
```bash
npm install my-package
```
</TabItem>
<TabItem value="yarn">
```bash
yarn add my-package
```
</TabItem>
<TabItem value="pnpm">
```bash
pnpm add my-package
```
</TabItem>
</Tabs>By default, each Tabs instance manages its own selected tab. To sync the selection across multiple tab groups, give them the same groupId.
Use the HTML <details> element for collapsible/expandable content:
<details>
<summary>Click to expand</summary>
Hidden content goes here. You can include:
- Lists
- Code blocks
- Any other markdown content
</details>Standard markdown tables are supported with responsive horizontal scrolling on mobile:
| Feature | Status | Notes |
|-------------|-----------|----------------------|
| Admonitions | Supported | All five types |
| Code Blocks | Supported | With enhancements |
| Tables | Supported | Responsive scrolling |shipyard supports all standard markdown features:
Inline code- [x] and - [ ])