Use guide index as homepage root

README.md

@@ -17,6 +17,7 @@ A clean and modern Bootstrap-based template for phpDocumentor, designed to impro
 - Responsive and mobile-friendly
 - Styled code blocks and documentation elements
 - Improved tables of contents and element listings
+- Designed for documentation sets that provide guides
 
 ## Installation
 
@@ -28,7 +29,7 @@ composer require --dev fast-forward/phpdoc-bootstrap-template
 
 ## Usage
 
-Reference the template from vendor in your phpdoc.xml:
+Reference the template from vendor in your phpdoc.xml. This template is designed for projects that ship guides, and the guide output should point to the documentation root (`.`) so the guide index becomes the homepage:
 
 ```xml
 <?xml version="1.0" encoding="UTF-8" ?>
@@ -47,6 +48,12 @@ Reference the template from vendor in your phpdoc.xml:
                 <path>src</path>
             </source>
         </api>
+        <guide format="rst">
+            <source dsn=".">
+                <path>docs</path>
+            </source>
+            <output>.</output>
+        </guide>
     </version>
 
     <template name="vendor/fast-forward/phpdoc-bootstrap-template" />
@@ -65,6 +72,8 @@ Or with a config file:
 vendor/bin/phpdoc --config phpdoc.xml
 ```
 
+With this setup, the guide `index` document is rendered as the root `index.html`.
+
 ## Requirements
 
 - PHP 8.3+
@@ -88,4 +97,4 @@ Contributions are welcome. Please open an issue or submit a pull request.
 
 ## 📄 License
 
-This package is licensed under the MIT License. See the [LICENSE](LICENSE) file for more details.
+This package is licensed under the MIT License. See the [LICENSE](LICENSE) file for more details.

components/sidebar.html.twig

@@ -26,26 +26,26 @@
             <ul class="nav nav-pills flex-column">
                 {% if project.settings.custom['graphs.enabled'] %}
                     <li class="nav-item">
-                        <a class="nav-link link-body-emphasis d-flex align-items-center gap-2" href="graphs/classes.html">
+                        <a class="nav-link link-body-emphasis d-flex align-items-center gap-2" href="{{ path('graphs/classes.html') }}">
                             <i class="fas fa-project-diagram text-primary"></i>
                             <span>Class Diagram</span>
                         </a>
                     </li>
                 {% endif %}
                 <li class="nav-item">
-                    <a class="nav-link link-body-emphasis d-flex align-items-center gap-2" href="reports/deprecated.html">
+                    <a class="nav-link link-body-emphasis d-flex align-items-center gap-2" href="{{ path('reports/deprecated.html') }}">
                         <i class="fas fa-exclamation-triangle text-warning"></i>
                         <span>Deprecated</span>
                     </a>
                 </li>
                 <li class="nav-item">
-                    <a class="nav-link link-body-emphasis d-flex align-items-center gap-2" href="reports/errors.html">
+                    <a class="nav-link link-body-emphasis d-flex align-items-center gap-2" href="{{ path('reports/errors.html') }}">
                         <i class="fas fa-bug text-danger"></i>
                         <span>Errors</span>
                     </a>
                 </li>
                 <li class="nav-item">
-                    <a class="nav-link link-body-emphasis d-flex align-items-center gap-2" href="reports/markers.html">
+                    <a class="nav-link link-body-emphasis d-flex align-items-center gap-2" href="{{ path('reports/markers.html') }}">
                         <i class="fas fa-bookmark text-info"></i>
                         <span>Markers</span>
                     </a>
@@ -61,12 +61,12 @@
 
             <ul class="nav nav-pills flex-column">
                 <li class="nav-item">
-                    <a class="nav-link link-body-emphasis d-flex align-items-center gap-2" href="indices/files.html">
+                    <a class="nav-link link-body-emphasis d-flex align-items-center gap-2" href="{{ path('indices/files.html') }}">
                         <i class="fas fa-file-code text-secondary"></i>
                         <span>Files</span>
                     </a>
                 </li>
             </ul>
         </li>
     </ul>
-</nav>
+</nav>

graphs/class.html.twig

@@ -1,5 +1,4 @@
 {% extends 'base.html.twig' %}
-{% set baseUrl = renderBaseUrlHeader() %}
 
 {% block stylesheets %}
 {% endblock %}
@@ -40,7 +39,7 @@
                 id="graph-container"
             >
                 <img
-                    src="graphs/classes.svg"
+                    src="{{ path('graphs/classes.svg') }}"
                     id="scene"
                     alt="Class diagram"
                     class="img-fluid d-block mx-auto"
@@ -88,4 +87,4 @@
             });
         })();
     </script>
-{% endblock %}
+{% endblock %}

js/search.js.twig

@@ -65,7 +65,7 @@ var Search = (function () {
         var summary = result.summary ? escapeHtml(result.summary) : '';
         var fqsen = result.fqsen ? escapeHtml(result.fqsen) : '';
         var name = escapeHtml(result.name || 'Untitled');
-        var url = document.baseURI + result.url;
+        var url = result.url;
 
         return '' +
             '<li class="list-group-item px-3 py-3">' +
@@ -208,4 +208,4 @@ window.addEventListener('DOMContentLoaded', function () {
 
 window.addEventListener('load', function () {
     Search.init();
-});
+});

js/searchIndex.js.twig

@@ -1,4 +1,3 @@
-{% set baseUrl = renderBaseUrlHeader() %}
 Search.appendIndex(
     [
         {% for element in project.indexes.elements %}

layout.html.twig

@@ -6,8 +6,31 @@
         <title>{% block title %}{{ project.name }}{% endblock %}</title>
     {% endblock %}
 
+    {% set currentDestination = destinationPath|default('') %}
+    {% if (currentDestination is empty) and env is not null %}
+        {% set currentDestination = env.currentFileDestination|default('') %}
+    {% endif %}
+
+    {% set normalizedDestination = currentDestination
+        |split('#')|first
+        |split('?')|first
+        |replace({'./': '', '.\\': ''})
+        |trim('/')
+    %}
+
+    {% set destinationDepth = normalizedDestination ? (normalizedDestination|split('/')|length - 1) : 0 %}
+    {% set baseHref = './' %}
+
+    {% if destinationDepth > 0 %}
+        {% set baseSegments = [] %}
+        {% for i in 1..destinationDepth %}
+            {% set baseSegments = baseSegments|merge(['../']) %}
+        {% endfor %}
+        {% set baseHref = baseSegments|join('') %}
+    {% endif %}
+
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
-    {{ renderBaseUrlHeader() }}
+    <base href="{{ baseHref }}">
 
     {% block stylesheets %}
         <!-- Bootstrap -->
@@ -20,7 +43,7 @@
 
         <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/styles/default.min.css">
 
-        <link rel="stylesheet" href="{{ template_path }}css/base.css">
+        <link rel="stylesheet" href="{{ path('css/base.css') }}">
     {% endblock %}
 </head>
 <body>
@@ -84,9 +107,9 @@
 
         <script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/highlight.min.js"></script>
 
-        <script src="js/template.js"></script>
-        <script src="js/search.js"></script>
-        <script defer src="js/searchIndex.js"></script>
+        <script src="{{ path('js/template.js') }}"></script>
+        <script src="{{ path('js/search.js') }}"></script>
+        <script defer src="{{ path('js/searchIndex.js') }}"></script>
     {% endblock %}
 </body>
 </html>

template.xml

@@ -5,7 +5,6 @@
   <email>github@mentordosnerds.com</email>
   <version>1.0.0</version>
   <transformations>
-    <transformation writer="twig" source="index.html.twig" artifact="index.html"/>
     <transformation writer="twig" query="files" source="file.html.twig" />
     <transformation writer="sourcecode" query="files" source="source/file.source.txt.twig" artifact="files/{{path}}.txt" />
     <transformation writer="twig" query="indexes.namespaces" source="namespace.html.twig" />