Markflat Editor Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require auvernhatinternet/markflat-editor
   

   Add to config/bundles.php:

   MarkFlatEditor\MarkFlatEditorBundle::class => ['all' => true],
   

2. Configure .env:

   ADMIN_PASSWORD=your_secure_password_here
   

3. First Use Case: Access the editor at /admin?password=your_secure_password_here. The interface will allow you to edit Markdown files stored in a predefined directory (default: var/markflat/).

Key First Steps

• Locate the default storage path: Check config/packages/markflat_editor.yaml (if it exists) or inspect the bundle’s default configuration for the storage_path setting.
• Test the editor: Create a sample Markdown file in the storage directory (e.g., var/markflat/test.md) and verify it appears in the admin panel.
• Render Markdown: Use Twig to render the Markdown content in your templates:

  {{ render_markdown('var/markflat/test.md') }}
  

Implementation Patterns

Workflow Integration

1. File Management:

   • Create/Edit Files: Use the admin panel to add or modify Markdown files. The editor provides a WYSIWYG-like interface for Markdown syntax.
   • File Structure: Organize files in subdirectories within the storage path (e.g., var/markflat/docs/guides/). The admin panel will reflect this structure.

2. Dynamic Content Rendering:

   • Twig Integration: Render Markdown files dynamically in templates:

     {% for file in get_markflat_files('var/markflat/docs') %}
       <h2>{{ file.name }}</h2>
       {{ render_markdown(file.path) }}
     {% endfor %}
     

   • Cache Control: Leverage Symfony’s cache system to optimize rendering performance for frequently accessed files.

3. Authentication & Security:

   • Password Protection: The ADMIN_PASSWORD in .env secures the admin panel. For production, consider:
     • Using Symfony’s security component to replace the password-based auth.
     • Implementing role-based access control (RBAC) for multi-user environments.
   • File Permissions: Ensure the storage directory (var/markflat/) has restrictive permissions (e.g., chmod 750).

4. Customization:

   • Override Templates: Extend the bundle’s Twig templates by copying them from vendor/markflat-editor/templates/ to your project’s templates/bundles/markflat_editor/.
   • Extend Functionality: Create custom Twig filters or functions to process Markdown files (e.g., extract metadata like frontmatter).

Example Use Cases

1. Documentation Site:

   • Store Markdown files in var/markflat/docs/.
   • Render them in a Twig template with navigation links generated from the file structure.

2. Blog System:

   • Use the editor to manage blog posts stored as Markdown.
   • Add metadata (e.g., title, date) via frontmatter and parse it in Twig:

     {% set post = parse_markflat_metadata('var/markflat/posts/2023-intro.md') %}
     <h1>{{ post.title }}</h1>
     <p>{{ post.date }}</p>
     {{ render_markdown('var/markflat/posts/2023-intro.md') }}
     

3. Multi-Language Support:

   • Store translations in separate directories (e.g., var/markflat/en/, var/markflat/fr/).
   • Dynamically switch content based on the user’s locale.

Gotchas and Tips

Pitfalls

1. Storage Path Configuration:

   • The bundle defaults to var/markflat/, but this can be overridden in config/packages/markflat_editor.yaml:

     markflat_editor:
         storage_path: '%kernel.project_dir%/custom/markflat'
     

   • Gotcha: Forgetting to create the directory manually or misconfiguring permissions will result in "file not found" errors.

2. Password Security:

   • The ADMIN_PASSWORD is stored in plaintext in .env. For production:
     • Use Symfony’s ParameterBag or env() function to encrypt the password.
     • Integrate with Symfony’s security system for hashed passwords.

3. Markdown Parsing Quirks:

   • The bundle uses a basic Markdown parser. For advanced features (e.g., tables, footnotes), consider:
     • Extending the parser or replacing it with a library like Parsedown.
     • Pre-processing Markdown files with custom logic before rendering.

4. Caching Issues:

   • Twig’s auto-reloading may not detect changes to Markdown files immediately. Clear the cache after edits:

     php bin/console cache:clear
     

Debugging Tips

1. Check Logs:

   • Enable debug mode (APP_DEBUG=1 in .env) to log errors related to file access or rendering.

2. Verify File Paths:

   • Use Symfony’s dump() to debug file paths:

     {{ dump(get_markflat_files('var/markflat')) }}
     

3. Test with Minimal Files:

   • Start with a single Markdown file to isolate issues (e.g., syntax errors, permission problems).

Extension Points

1. Custom Twig Functions:

   • Add a custom Twig extension to parse Markdown files with additional logic:

     // src/Twig/AppExtension.php
     namespace App\Twig;
     
     use Twig\Extension\AbstractExtension;
     use Twig\TwigFunction;
     
     class AppExtension extends AbstractExtension
     {
         public function getFunctions()
         {
             return [
                 new TwigFunction('custom_markdown_render', [$this, 'renderWithCustomLogic']),
             ];
         }
     
         public function renderWithCustomLogic(string $path): string
         {
             // Custom logic here
             return file_get_contents($path);
         }
     }
     

2. Event Listeners:

   • Listen for file changes or rendering events (if the bundle exposes events). Example for Symfony 7:

     // config/services.yaml
     App\EventListener\MarkFlatListener:
         tags:
             - { name: kernel.event_listener, event: markflat.editor.render, method: onRender }
     

3. Override Admin Panel:

   • Replace the entire admin interface by:
     1. Disabling the bundle’s routes.
     2. Creating a custom controller to handle file operations (e.g., using Symfony’s FileSystem component).

Configuration Quirks

1. Environment-Specific Settings:

   • Use %kernel.environment% to set different storage paths per environment:

     markflat_editor:
         storage_path: '%kernel.project_dir%/var/markflat_%kernel.environment%'
     

2. Disable Admin Panel:

   • Set admin_enabled: false in the config to hide the /admin route entirely:

     markflat_editor:
         admin_enabled: false
     

3. File Filtering:

   • The bundle may not filter hidden files (e.g., .gitignore). Add a custom Twig filter to exclude them:

     {% set visible_files = get_markflat_files('var/markflat')|reject('isHiddenFile') %}