- How do I install and set up labrodev/laravel-markdownable in Laravel?
- Run `composer require labrodev/laravel-markdownable` to install. Publish the config with `php artisan vendor:publish --tag=markdownable-config` or set `MARKDOWNABLE_PAGES_PATH` in your `.env` file to define the directory where your Markdown files are stored. No database or additional setup is required.
- Can I use this package for a blog or documentation site?
- Yes, this package is ideal for blogs or documentation sites. Store your Markdown files in the configured directory, use YAML front matter for metadata (like titles, descriptions, and SEO tags), and access them via `Markdownable::getPageBySlug()`. The `PageData` object provides structured data for Blade templates or SEO packages.
- What Laravel versions does this package support?
- The package is tested with Laravel 9+ and requires PHP 8.0+. Check the `composer.json` of the package for the latest supported versions. It follows Laravel’s semantic versioning, so minor updates should align with Laravel’s release cycle.
- How do I cache the parsed Markdown pages to improve performance?
- Use Laravel’s cache system to store `PageData` objects. For example, wrap `Markdownable::getPageBySlug()` in `Cache::remember()` with a key like `pages:{$slug}`. Alternatively, pre-render HTML during deployments or use a CDN like Varnish for high-traffic pages.
- Does this package support multi-language content (i18n)?
- No, the package does not include built-in multi-language support. You’ll need to implement a custom solution, such as storing Markdown files in language-specific directories (e.g., `en/about.md`, `es/about.md`) and extending the `MarkdownPageReader` to handle locale logic.
- How do I integrate this with Laravel SEO packages like spatie/laravel-seo?
- Use the `PageData::toArray()` method to extract metadata like `meta_title`, `meta_description`, and `og_image` from the YAML front matter. Pass this array to `spatie/laravel-seo` or directly to Blade templates for dynamic meta tags. The package ensures consistent key naming for easy integration.
- What if I need to store Markdown files in S3 or another cloud storage?
- The package assumes local file storage, but you can create a custom `MarkdownPageFileReader` by implementing the `MarkdownPageFileReaderContract`. This allows you to replace the default file reader with one that fetches files from S3 or another storage service.
- Can I mock or swap out the Markdown parser for testing?
- Yes, the package provides contracts (`MarkdownPageFileReaderContract`, `FrontMatterParserContract`, `MarkdownConverterContract`) that make it easy to mock dependencies. For example, you can create a fake `MarkdownPageFileReader` in tests to return predefined Markdown content without hitting the filesystem.
- What happens if my Markdown file has complex syntax (e.g., tables, footnotes) not supported by GFM?
- The package uses League CommonMark with GitHub Flavored Markdown (GFM), which covers most use cases. For advanced syntax, you can extend the `MarkdownToHtmlConverter` or switch to a more flexible parser like `cebe/markdown` by binding a custom implementation in the service container.
- How do I list all available Markdown pages in my Laravel app?
- Use the `Markdownable::listPages()` method to retrieve an array of `PageData` objects for all Markdown files in the configured directory. This is useful for generating sitemaps, navigation menus, or API endpoints listing all pages.