Links

Links connect your documentation pages together and point to external resources. Mordoc supports standard markdown link syntax with enhanced styling options.

Basic Link Syntax

Create links using markdown bracket notation:

[Link Text](URL)

Example

[Visit our website](https://example.com)

Result: Visit our website

Link Types

External Links

Link to websites outside your documentation:

[Node.js Official Site](https://nodejs.org)
[GitHub](https://github.com)

External links:

• Node.js Official Site
• GitHub

Internal Links

Link to other pages within your documentation using relative paths:

[Getting Started](/get-started/creating-project)
[Configuration Guide](/configuration/sidenav)

Internal links:

• Getting Started
• Configuration Guide

Internal Link Path Rules

• Start with / for absolute paths from site root
• Match the file path without the .md extension
• Use lowercase and hyphens

Anchor Links

Link to specific sections within a page using heading IDs:

[Jump to Installation](#installation)
[See Prerequisites](/get-started/creating-project#prerequisites)

Anchor links:

• Jump to Link Types
• Jump to Styling

Heading IDs are automatically generated from heading text:

• Converted to lowercase
• Spaces become hyphens
• Special characters removed

Email Links

Create mailto links:

[Contact Support](mailto:support@example.com)

Result: Contact Support

Download Links

Link to downloadable files in your public/ directory:

[Download PDF Guide](/downloads/guide.pdf)
[Get Template](/templates/starter.zip)

Link with Title Attribute

Add a tooltip that appears on hover:

[Mordoc Docs](https://docs.mordoc.com "Visit Mordoc Documentation")

The text in quotes becomes the title attribute shown on hover.

Reference-Style Links

For cleaner markdown when using the same link multiple times:

Check out [Mordoc][1] for documentation tools.
Learn more about [markdown syntax][1].

[1]: https://mordoc.com "Mordoc Homepage"

Auto-Linking URLs

Wrap URLs in angle brackets to make them clickable:

<https://example.com>
<mailto:hello@example.com>

Results in:

• https://example.com
• mailto:hello@example.com

Styling Links

Customize link appearance through the configuration file.

Edit config/styles/main.json:

{
  "links": {
    "color": "#3b82f6",
    "hoverColor": "#2563eb",
    "underline": true,
    "underlineOnHover": true,
    "fontWeight": "400",
    "externalIcon": true
  }
}

Available Style Properties

Example Configurations

Minimal Style (No Underlines)

{
  "links": {
    "color": "#3b82f6",
    "hoverColor": "#1d4ed8",
    "underline": false,
    "underlineOnHover": true
  }
}

Bold Links with Icon

{
  "links": {
    "color": "#059669",
    "hoverColor": "#047857",
    "fontWeight": "600",
    "underline": false,
    "externalIcon": true
  }
}

Subtle Style

{
  "links": {
    "color": "inherit",
    "hoverColor": "#3b82f6",
    "underline": false,
    "underlineOnHover": true,
    "fontWeight": "500"
  }
}

Link Best Practices

Writing Good Link Text

Do:

• Use descriptive text: [Read the installation guide](/guides/install)
• Make links standalone: [Learn about API authentication](/api/auth)
• Keep it concise: [View examples](/examples)

Don't:

• Use generic text: [Click here](/guides/install)
• Make links too long: [Click here to read the complete step-by-step installation guide with screenshots](/guides/install)
• Use URLs as text: [https://example.com/guides/install](https://example.com/guides/install)

Link Structure

1. Link to Specific Sections: Use anchor links when referencing specific content
2. Avoid Broken Links: Verify internal links point to existing pages
3. Update Links: When reorganizing content, update all related links
4. Test External Links: Periodically check external links aren't broken

Accessibility

• Use meaningful link text that describes the destination
• Avoid "click here" or "read more" without context
• Ensure link colors have sufficient contrast
• Don't rely on color alone to indicate links

<!-- Good -->
[View the installation requirements](/prerequisites/nodejs)

<!-- Bad -->
[Click here](/prerequisites/nodejs) to see requirements

Button-Style Links

For prominent call-to-action links, use the card component:

{% card title="Get Started" href="/get-started/creating-project" %}
Create your first documentation project in minutes.
{% /card %}

See Cards & Card Grid for more details.

Common Patterns

Navigation Links

**In this guide:**
- [Installation](#installation)
- [Configuration](#configuration)
- [Usage](#usage)
- [Troubleshooting](#troubleshooting)

Related Pages

**Related:**
- [Understanding Project Structure](/get-started/project-structure)
- [Side Navigation Configuration](/configuration/sidenav)
- [Deployment Guide](/deployment/build)

External Resources

**External Resources:**
- [Markdown Guide](https://www.markdownguide.org)
- [GitHub Documentation](https://docs.github.com)
- [MDN Web Docs](https://developer.mozilla.org)

Troubleshooting

Link Not Working

• Verify the path starts with / for internal links
• Check file exists at the specified path
• Ensure path matches file structure exactly
• Remember paths are case-sensitive on some platforms

Anchor Link Not Working

• Confirm heading exists on the target page
• Verify heading ID matches (check generated IDs)
• Use lowercase and hyphens in anchor IDs

External Link Opens in Same Tab

External links should automatically open in new tabs. If not, check your build configuration.

Examples

Complete Page with Links

# Getting Started

Welcome to our documentation. Follow these steps:

1. [Install prerequisites](/prerequisites/nodejs)
2. [Create your project](/get-started/creating-project)
3. [Deploy your site](/deployment/build)

Need help? [Contact support](mailto:support@example.com) or visit our [community forum](https://forum.example.com).

**External Resources:**
- [Official Markdown Spec](https://commonmark.org)
- [GitHub Flavored Markdown](https://github.github.com/gfm/)

Next Steps

• Images - Embed images in your documentation
• Lists - Create ordered and unordered lists
• Code Blocks - Add syntax-highlighted code examples