From ab1800defc7dfedc1fee0daefdb869b027aa89d0 Mon Sep 17 00:00:00 2001
From: Kevin Papst <kpapst@gmx.net>
Date: Mon, 16 Dec 2024 16:13:45 +0100
Subject: [PATCH] improve export template docs

---
 .../developer/extending-kimai.md              | 13 +++++++++++
 collections/_documentation/export.md          | 23 ++++++-------------
 2 files changed, 20 insertions(+), 16 deletions(-)

diff --git a/collections/_documentation/developer/extending-kimai.md b/collections/_documentation/developer/extending-kimai.md
index d4f513634..d53d9c778 100644
--- a/collections/_documentation/developer/extending-kimai.md
+++ b/collections/_documentation/developer/extending-kimai.md
@@ -157,6 +157,19 @@ Every invoice renderer class will be automatically available, after refreshing t
 This "magic" happens in the [InvoiceServiceCompilerPass]({{ site.kimai_v2_file }}/src/DependencyInjection/Compiler/InvoiceServiceCompilerPass.php),
 which finds the classes by the interface `RendererInterface`.
 
+## Export templates
+
+Export documents are searched in two locations:
+
+- `var/export/` - does not exist by default, please create it when you add a new template
+- `templates/export/renderer/` - don't change files in here, will be overwritten with the next update
+
+If you create customer templates, beware of these rules:
+
+- You should store your templates in `var/export/`, as this directory is not shipped with Kimai and not touched during updates (instead of `templates/export/renderer/`)
+- You can configure different search directories through the config key `kimai.export.documents` if you want to add additional template source directories
+- You can hide the default templates by setting the key `kimai.export.defaults` to an empty array / null
+
 ## Adding export renderer
 
 An export renderer is a class implementing `App\Export\RendererInterface` and it is responsible to convert an array of
diff --git a/collections/_documentation/export.md b/collections/_documentation/export.md
index 8be4e565d..0b0d71a87 100644
--- a/collections/_documentation/export.md
+++ b/collections/_documentation/export.md
@@ -35,33 +35,24 @@ For further information read the [timesheet documentation]({% link _documentatio
 
 ## Adding export templates
 
-Since Kimai 1.9 you can add templates for PDF and HTML exports.
+Kimai supports custom PDF and HTML export templates.
 
-Export documents are searched in two locations:
-
-- `var/export/` - does not exist by default, please create it when you add a new template
-- `templates/export/renderer/` - don't change files in here, will be overwritten with the next update
+Those export templates are searched in the location `var/export/`, which does not exist by default, please create it when you add your first template.
 
 Be aware of the following rules:
 
 - HTML templates have the file extension `.html.twig`
 - PDF templates have the file extension `.pdf.twig`
-- Templates are addressed by their filename 
-- You can use every document name only once.
-  - Having `var/export/default.html.twig` and `templates/export/renderer/default.html.twig` will lead to unpredictable results 
-  - Use unique filenames and prefix them with your company name, eg `acme-export.html.twig` 
-- You should store your templates in `var/export/`, as this directory is not shipped with Kimai and not touched during updates
-- You can configure different search directories through the config key `kimai.export.documents` if you want to add additional template source directories 
-- You can hide the default templates by setting the key `kimai.export.defaults` to an empty array / null
+- You can use every template filename only once, as they are used as reference
+- The names `default.html.twig`, `default.pdf.twig`, `default-budget.pdf.twig`, `default-internal.pdf.twig`, `timesheet.pdf.twig` are reserved
+- Use unique filenames and prefix them with your company name, eg `company-export.html.twig` 
  
 After you created a new or updated an existing template, you have to clear the cache to see the results:
 {% include snippets/cache-refresh.md %} 
 
-Please copy & paste one of [default templates]({{ site.kimai_v2_repo }}/tree/main/templates/export/renderer) to `var/export/` 
-as starting point and rename it afterwards.
+### How to start
 
-You can translate the button for your template, by adding its name to the export translation file, eg. `translations/export.en.xlf`.
-Internally for each template a new ExportRenderer service is registered, called `exporter_renderer.filename_EXT_twig` (see `ExportServiceCompilerPass`).   
+Copy & paste the [default templates]({{ site.kimai_v2_repo }}/blob/main/templates/export/pdf-layout.html.twig) to `var/export/company-template.pdf.twig` as starting point.
 
 ## PDF Templates