Guides Markdown Laravel Package

Getting Started

Install via Composer as a development dependency:

composer require --dev phpdocumentor/guides-markdown

Ensure phpdocumentor/guides (v3 or later) is also installed — this package extends the Guides core and requires it. Start by placing Markdown files (e.g., index.md, guide.md) in your documentation source directory (commonly docs/ or resources/docs/). The parser automatically recognizes .md and .markdown extensions and processes them during guide builds via phpdocumentor guide:render. The first use case is straightforward: replace XML or reStructuredText pages with Markdown for simpler authoring while retaining full Guides rendering (PDF, HTML, etc.).

Implementation Patterns

• Mixed-Format Documentation: Organize content in a single docs/ directory with .md, .rst, and .xml files coexisting — Guides automatically routes each to the correct parser.
• Custom Page Extensions: Use front matter (YAML) in Markdown files to control metadata and page hierarchy:

  ---
  title: Getting Started
  weight: 10
  ---
  # Introduction
  ...
  

• Custom Directive Integration: Extend Markdown with custom shortcodes using Guides’ ::directive:: syntax — e.g., ::note{type="tip"}This is important:: renders as styled callouts in HTML.
• CI/CD Integration: Add phpdocumentor guide:render --config=docs/guide.yml to your build pipeline; Markdown support is transparent — no extra CLI flags needed.
• Theme Customization: Customize output by extending the default HTML theme; Markdown content inherits all Guides theme hooks (e.g., @section('content')).

Gotchas and Tips

• Strict Yaml Parsing: Front matter must be valid YAML and exactly enclosed between --- delimiters at the top of the file — trailing whitespace or extra lines before --- break parsing.
• HTML Escaping: Inline HTML in Markdown is preserved but not re-parsed — ensure well-formed tags (e.g., <span class="important">) or escape them in raw HTML blocks:

  ```html
  <strong>Not rendered as HTML</strong>
  ```
  

• Link Resolution: Relative Markdown links like [Guide](guide.md) work in source files but resolve only to other Markdown pages by default. Linking to non-Markdown pages requires explicit paths (e.g., [API](api/index.html)).
• Syntax Highlighting: Code blocks use Guides’ default theme — customize with {.language-php} after the fence (e.g., ```php { .no-line-numbers }).
• Parser Versioning: The package uses league/commonmark, so check its compatibility notes — e.g., strict GFM table parsing changed in v2.0+. Align versions across dependencies if tables break unexpectedly.
• Missing Features: Advanced Markdown extensions (e.g., footnotes, definition lists) may not render as expected unless enabled via CommonMark config overrides in guide.yml.