Getting Started

Minimal Setup

Install via Composer

composer require dontdrinkandroot/gitki-bundle

Add the bundle to config/bundles.php in a Symfony project:

return [
    // ...
    DontDrinkAndRoot\GitkiBundle\DontDrinkAndRootGitkiBundle::class => ['all' => true],
];

Configure the Bundle Update config/packages/dontdrink_and_root_gitki.yaml with your Git repository path and branch:
```
dontdrink_and_root_gitki:
    repository_path: '%kernel.project_dir%/var/wiki_repo'
    branch: 'master'
```
Initialize the Wiki Repository Run the command to set up the Git repository (if it doesn’t exist):
```
php bin/console gitki:init
```
First Use Case: Embedding Wiki Content Use the gitki Twig extension to render wiki pages:
```
{{ gitki('GettingStarted') }}
```
This assumes a Markdown file named GettingStarted.md exists in the wiki repository.

Implementation Patterns

Core Workflows

Rendering Wiki Pages
- Use the gitki Twig function to embed wiki content dynamically:
```
{% set content = gitki('ProjectDocumentation') %}
{{ content|raw }}  {# Render raw Markdown #}
```
- For static pages, cache the rendered output (e.g., via Symfony’s cache system) to avoid repeated Git operations.
Editing Wiki Content
- Provide a user-friendly interface (e.g., a form) to edit Markdown files. Use the gitki:edit command to stage changes:
```
php bin/console gitki:edit "GettingStarted.md" --message="Updated documentation"
```
- Integrate with a WYSIWYG editor (e.g., EasyMDE) for a richer editing experience.
Version Control Integration
- Leverage Git’s history to track changes:
```
php bin/console gitki:log "GettingStarted.md"  {# View commit history #}
php bin/console gitki:show "GettingStarted.md"@{HEAD~1}  {# View previous version #}
```
- Use Symfony events (e.g., kernel.terminate) to auto-commit changes from your application logic.
Access Control
- Restrict access to wiki pages using Symfony’s security system. Example in security.yaml:
```
access_control:
    - { path: ^/wiki, roles: ROLE_WIKI_EDITOR }
```
- Combine with the bundle’s gitki:acl command to manage permissions per-file.

Integration Tips

Customize Markdown Processing Override the default Markdown parser by extending the DontDrinkAndRoot\GitkiBundle\Parser\MarkdownParserInterface and configuring it in services.yaml:
```
services:
    App\CustomMarkdownParser:
        tags: ['dontdrink_and_root_gitki.parser']
```

Route-Based Wiki Pages Map wiki pages to Symfony routes for SEO-friendly URLs. Example in config/routes.yaml:

wiki_page:
    path: /wiki/{page}
    controller: App\Controller\WikiController::show
    defaults:
        _gitki_page: '%kernel.project_dir%/var/wiki_repo/%page%.md'

Asset Management Store static assets (images, PDFs) in the wiki repository. Reference them in Markdown:
```
![Logo](./assets/logo.png)
```
Serve assets via Symfony’s Asset component or a dedicated route.
Search Functionality Use the gitki:search command to index wiki content and integrate with Elasticsearch or Algolia for full-text search.

Gotchas and Tips

Pitfalls

Repository Path Permissions Ensure the configured repository_path is writable by the web server user (e.g., www-data). Use:
```
chown -R www-data:www-data %kernel.project_dir%/var/wiki_repo
```
Git Hooks Conflicts Avoid manual Git hooks (e.g., pre-commit) in the wiki repository, as the bundle may override them. Use Symfony events instead.
Markdown Parsing Quirks The default Markdown parser may not support advanced syntax (e.g., tables, footnotes). Extend the parser or use a library like Parsedown Extra.
Caching Pitfalls Clear the cache after editing wiki pages to reflect changes:
```
php bin/console cache:clear
```
For dynamic rendering, use gitki('page', { 'cache': false }).

Debugging

Enable Verbose Logging Set the debug parameter in dontdrink_and_root_gitki.yaml to true to log Git operations:
```
dontdrink_and_root_gitki:
    debug: true
```
Check Git Status Use the gitki:status command to verify the repository state:
```
php bin/console gitki:status
```
Handle Merge Conflicts If conflicts arise during edits, resolve them manually in the repository and use:
```
php bin/console gitki:commit --message="Resolved conflicts"
```

Extension Points

Custom Commands Extend the bundle’s command system by creating a custom command that interacts with the wiki repository. Example:

namespace App\Command;

use DontDrinkAndRoot\GitkiBundle\Command\GitkiCommand;
use Symfony\Component\Console\Input\InputArgument;

class CustomWikiCommand extends GitkiCommand {
    protected function configure() {
        $this->setName('app:wiki:backup')
             ->addArgument('path', InputArgument::REQUIRED);
    }

    protected function execute(InputInterface $input, OutputInterface $output) {
        $this->git->execute(['archive', '--output', $input->getArgument('path'), 'HEAD']);
    }
}

Event Listeners Listen to wiki events (e.g., gitki.page.rendered) to modify rendered content or trigger side effects:

namespace App\EventListener;

use DontDrinkAndRoot\GitkiBundle\Event\PageRenderedEvent;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

class WikiListener implements EventSubscriberInterface {
    public static function getSubscribedEvents() {
        return [
            PageRenderedEvent::NAME => 'onPageRendered',
        ];
    }

    public function onPageRendered(PageRenderedEvent $event) {
        $content = $event->getContent();
        // Modify content (e.g., add a footer)
        $event->setContent($content . '<footer>Generated by Gitki</footer>');
    }
}

Override Templates Customize the default Twig templates by copying them from the bundle’s Resources/views/ to your project’s templates/dontdrink_and_root_gitki/ directory.

Configuration Quirks

Branch-Specific Config The bundle defaults to the master branch. To use a feature branch dynamically:
```
dontdrink_and_root_gitki:
    branch: '%env(GITKI_BRANCH)%'  {# Set via environment variable #}
```
Submodule Support The bundle does not natively support Git submodules. For nested repositories, consider using a custom parser or post-processing step.
Large Repositories Performance may degrade with repositories >1GB. Optimize by:
- Using sparse checkouts (git sparse-checkout init).
- Limiting the number of rendered pages per request.

Gitki Bundle Laravel Package