Markdown Features

shipyard supports enhanced markdown features that make your documentation richer and more interactive.

Admonitions

Admonitions (also called callouts) are a great way to highlight important information:

Custom Titles

You can add custom titles to admonitions:

Details (Collapsible Sections)

Use the HTML <details> element for collapsible content:

Click to expand

This content is hidden by default but can be revealed by clicking the summary.

You can include:

• Lists
• Code blocks
• Any other markdown content

Code Blocks

Standard code blocks with syntax highlighting:

function greet(name) {
  console.log(`Hello, ${name}!`);
}

greet("shipyard");

Code Block Titles

Add titles to code blocks to show filenames or descriptions:

export function greet(name) {
  console.log(`Hello, ${name}!`);
}

def greet(name):
    print(f"Hello, {name}!")

greet("shipyard")

Line Numbers

Display line numbers in code blocks:

function calculateSum(numbers) {
  let sum = 0;
  for (const num of numbers) {
    sum += num;
  }
  return sum;
}

Start from a custom line number:

// This code starts at line 10
const config = {
  theme: 'dark',
  language: 'en',
};

Line Highlighting

Highlight specific lines using curly brace syntax:

function processData(data) {
  const validated = validate(data);  // This line is highlighted
  const transformed = transform(validated);
  return {                           // Lines 4-6 are highlighted
    success: true,
    data: transformed,
  };
}

Magic Comments

Use comments to highlight lines without showing the comment:

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);
}

Combined Features

Combine titles, line numbers, and highlighting:

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;
}

.admonition {
  border-left: 4px solid var(--primary-color);
  padding: 1rem;
  margin: 1rem 0;
}

Tables

Feature	Status	Notes
Admonitions	Supported	All types available
Code Blocks	Supported	With syntax highlighting
Tables	Supported	With horizontal scroll on mobile
Details	Supported	Native HTML element

Links and References

• Internal link to installation
• External link
• Link to blog

Emphasis and Formatting

• Bold text for emphasis
• Italic text for subtle emphasis
• Strikethrough for deleted content
• inline code for technical terms
• Links for references

Lists

Unordered Lists

• First item
• Second item
  • Nested item
  • Another nested item
• Third item

Ordered Lists

1. First step
2. Second step
   1. Sub-step A
   2. Sub-step B
3. Third step

Task Lists

• Completed task
• Pending task
• Another pending task

Blockquotes

This is a blockquote. Use it for quotes or to highlight important passages.

Blockquotes can span multiple paragraphs.

Images

Images can be added with standard markdown syntax:

![Alt text](./image.png)

Horizontal Rules

Use three dashes to create a horizontal rule:

---

Conclusion

These markdown features help you create rich, interactive documentation that’s easy to read and navigate.