Hidev Readme Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require hiqdev/hidev-readme
   

   Ensure you're using HiDev (the parent tool) as a dependency in your project.

2. Configuration: Add to your hidev-config.php (or equivalent HiDev config file):

   return [
       'plugins' => [
           'hiqdev/hidev-readme' => [
               'enabled' => true,
               'template' => '@root/templates/README.md.twig', // Path to your Twig template
           ],
       ],
   ];
   

3. First Use Case: Generate a basic README.md by running:

   hidev readme:generate
   

   This will render your template with default sections (e.g., badges, project info).

Implementation Patterns

Core Workflows

1. Template-Based Generation:

   • Use Twig templates (e.g., @root/templates/README.md.twig) to define structure.
   • Example template snippet:

     # {{ project.name }}
     
     [![Build Status]({{ badgeUrl('travis') }})]({{ project.travisUrl }})
     
     ## Installation
     ```bash
     composer require {{ project.name }}
     

2. Dynamic Sections:

   • Leverage HiDev’s project object (e.g., {{ project.description }}, {{ project.authors }}).
   • Extend with custom sections via config:

     'sections' => [
         'usage' => '@root/templates/sections/usage.md.twig',
         'contributing' => '@root/templates/sections/contributing.md.twig',
     ],
     

3. Badge Integration:

   • Use markdownBadges (e.g., {{ badge('github-actions') }}) for dynamic badges.
   • Configure badge sources in hidev-config.php:

     'badges' => [
         'github-actions' => 'https://github.com/{vendor}/{name}/workflows/{workflow}/badge.svg',
     ],
     

4. CLI Integration:

   • Run hidev readme:generate to regenerate README.md after changes.
   • Use hidev readme:watch (if supported) for live updates during development.

Integration Tips

• Laravel-Specific:

  • Map HiDev’s project object to Laravel’s composer.json metadata:

    'project' => [
        'name' => 'vendor/package',
        'description' => json_decode(file_get_contents('composer.json'))->description,
    ],
    

  • Use Laravel’s Service Providers to inject HiDev config:

    $this->app->singleton('hidev.config', function () {
        return require __DIR__.'/../../hidev-config.php';
    });
    

• Custom Templates:

  • Place templates in resources/views/hidev/ (Laravel convention).
  • Override default sections (e.g., README.md.twig) in your project.

• CI/CD:

  • Add to .github/workflows/:

    - name: Generate README
      run: vendor/bin/hidev readme:generate
    

Gotchas and Tips

Pitfalls

1. Deprecated Dependencies:

   • Uses Twig_Loader_String (deprecated in Twig 2.x). Update to Twig_Loader_Array if needed:

     'template' => ['README.md' => '{{ include("README.md.twig") }}'],
     

2. Config Overrides:

   • HiDev’s config schema may change between versions. Pin hiqdev/hidev-readme to a stable release (e.g., 0.6.2).

3. Badge URL Generation:

   • Hardcoded badge URLs (e.g., badgeUrl('travis')) may break if services rename endpoints. Override in config:

     'badges' => [
         'travis' => 'https://api.travis-ci.com/{vendor}/{name}.svg?branch=master',
     ],
     

4. Template Caching:

   • Twig templates aren’t auto-cached. Clear cache after template changes:

     hidev cache:clear
     

Debugging Tips

• Dry Runs: Use hidev readme:generate --dry-run to preview output without writing files.

• Template Errors: Check Twig syntax with:

  vendor/bin/twig README.md.twig
  

• HiDev Debug Mode: Enable verbose output:

  HIDEV_DEBUG=1 hidev readme:generate
  

Extension Points

1. Custom Badges: Extend markdownBadges in config to support new services (e.g., GitLab, Codecov).

2. Section Hooks: Add pre/post-generation hooks via HiDev’s event system:

   'events' => [
       'readme.beforeGenerate' => function () {
           // Modify project data dynamically
       },
   ],
   

3. Multi-Format Support: Generate README.txt alongside README.md by adding:

   'formats' => ['md', 'txt'],
   

4. Laravel Mix Integration: Process README.md through Laravel Mix for syntax highlighting:

   mix.postCss('resources/css/README.css', 'public/css', [
       require('prismjs'),
   ]);