diff --git a/packages/guides-cli/resources/schema/guides.xsd b/packages/guides-cli/resources/schema/guides.xsd
index bd326a1b8..c25cc6f6a 100644
--- a/packages/guides-cli/resources/schema/guides.xsd
+++ b/packages/guides-cli/resources/schema/guides.xsd
@@ -21,6 +21,7 @@
+
diff --git a/packages/guides-restructured-text/src/RestructuredText/Directives/MenuDirective.php b/packages/guides-restructured-text/src/RestructuredText/Directives/MenuDirective.php
index 66d164129..2d0074580 100644
--- a/packages/guides-restructured-text/src/RestructuredText/Directives/MenuDirective.php
+++ b/packages/guides-restructured-text/src/RestructuredText/Directives/MenuDirective.php
@@ -20,6 +20,8 @@
use phpDocumentor\Guides\RestructuredText\Parser\Directive;
use phpDocumentor\Guides\RestructuredText\Parser\DirectiveOption;
use phpDocumentor\Guides\RestructuredText\Toc\ToctreeBuilder;
+use phpDocumentor\Guides\Settings\ProjectSettings;
+use phpDocumentor\Guides\Settings\SettingsManager;
use function count;
@@ -28,12 +30,18 @@
* is for display only. It does not change the position of document in the document tree and can therefore be included
* all pages as navigation.
*
- * By default it displays a menu of the pages on level 1 up to level 2.
+ * By default, it displays a menu of the pages on level 1 up to level 2.
*/
final class MenuDirective extends BaseDirective
{
- public function __construct(private readonly ToctreeBuilder $toctreeBuilder)
- {
+ private SettingsManager $settingsManager;
+
+ public function __construct(
+ private readonly ToctreeBuilder $toctreeBuilder,
+ SettingsManager|null $settingsManager = null,
+ ) {
+ // if for backward compatibility reasons no settings manager was passed, use the defaults
+ $this->settingsManager = $settingsManager ?? new SettingsManager(new ProjectSettings());
}
public function getName(): string
@@ -49,7 +57,8 @@ public function process(
$parserContext = $blockContext->getDocumentParserContext()->getParser()->getParserContext();
$options = $directive->getOptions();
$options['glob'] = new DirectiveOption('glob', true);
- $options['globExclude'] ??= new DirectiveOption('globExclude', 'index,Index');
+ $indexName = $this->settingsManager->getProjectSettings()->getIndexName();
+ $options['globExclude'] ??= new DirectiveOption('globExclude', $indexName);
$toctreeFiles = $this->toctreeBuilder->buildToctreeEntries(
$parserContext,
diff --git a/packages/guides-restructured-text/src/RestructuredText/Directives/ToctreeDirective.php b/packages/guides-restructured-text/src/RestructuredText/Directives/ToctreeDirective.php
index 9afe04800..9b1e17784 100644
--- a/packages/guides-restructured-text/src/RestructuredText/Directives/ToctreeDirective.php
+++ b/packages/guides-restructured-text/src/RestructuredText/Directives/ToctreeDirective.php
@@ -21,6 +21,8 @@
use phpDocumentor\Guides\RestructuredText\Parser\DirectiveOption;
use phpDocumentor\Guides\RestructuredText\Parser\Productions\Rule;
use phpDocumentor\Guides\RestructuredText\Toc\ToctreeBuilder;
+use phpDocumentor\Guides\Settings\ProjectSettings;
+use phpDocumentor\Guides\Settings\SettingsManager;
/**
* Sphinx based Toctree directive.
@@ -33,11 +35,16 @@
*/
final class ToctreeDirective extends BaseDirective
{
+ private SettingsManager $settingsManager;
+
/** @param Rule $startingRule */
public function __construct(
private readonly ToctreeBuilder $toctreeBuilder,
private readonly Rule $startingRule,
+ SettingsManager|null $settingsManager = null,
) {
+ // if for backward compatibility reasons no settings manager was passed, use the defaults
+ $this->settingsManager = $settingsManager ?? new SettingsManager(new ProjectSettings());
}
public function getName(): string
@@ -52,7 +59,8 @@ public function process(
): Node|null {
$parserContext = $blockContext->getDocumentParserContext()->getParser()->getParserContext();
$options = $directive->getOptions();
- $options['globExclude'] ??= new DirectiveOption('globExclude', 'index,Index');
+ $indexName = $this->settingsManager->getProjectSettings()->getIndexName();
+ $options['globExclude'] ??= new DirectiveOption('globExclude', $indexName);
$toctreeFiles = $this->toctreeBuilder->buildToctreeEntries(
$parserContext,
diff --git a/packages/guides/src/DependencyInjection/GuidesExtension.php b/packages/guides/src/DependencyInjection/GuidesExtension.php
index 6db4af678..10d37c716 100644
--- a/packages/guides/src/DependencyInjection/GuidesExtension.php
+++ b/packages/guides/src/DependencyInjection/GuidesExtension.php
@@ -114,6 +114,7 @@ static function ($value) {
->scalarNode('theme')->end()
->scalarNode('input')->end()
->scalarNode('input_file')->end()
+ ->scalarNode('index_name')->end()
->scalarNode('output')->end()
->scalarNode('input_format')->end()
->arrayNode('output_format')
@@ -237,6 +238,10 @@ public function load(array $configs, ContainerBuilder $container): void
}
}
+ if (isset($config['index_name']) && $config['index_name'] !== '') {
+ $projectSettings->setIndexName((string) $config['index_name']);
+ }
+
if (isset($config['output'])) {
$projectSettings->setOutput((string) $config['output']);
}
diff --git a/packages/guides/src/Handlers/ParseDirectoryHandler.php b/packages/guides/src/Handlers/ParseDirectoryHandler.php
index 4c7075899..8851e4b80 100644
--- a/packages/guides/src/Handlers/ParseDirectoryHandler.php
+++ b/packages/guides/src/Handlers/ParseDirectoryHandler.php
@@ -21,20 +21,28 @@
use phpDocumentor\Guides\Event\PreParseProcess;
use phpDocumentor\Guides\FileCollector;
use phpDocumentor\Guides\Nodes\DocumentNode;
+use phpDocumentor\Guides\Settings\ProjectSettings;
+use phpDocumentor\Guides\Settings\SettingsManager;
use Psr\EventDispatcher\EventDispatcherInterface;
+use function array_map;
use function assert;
+use function explode;
+use function implode;
use function sprintf;
final class ParseDirectoryHandler
{
- private const INDEX_FILE_NAMES = ['index', 'Index'];
+ private SettingsManager $settingsManager;
public function __construct(
private readonly FileCollector $fileCollector,
private readonly CommandBus $commandBus,
private readonly EventDispatcherInterface $eventDispatcher,
+ SettingsManager|null $settingsManager = null,
) {
+ // if for backward compatibility reasons no settings manager was passed, use the defaults
+ $this->settingsManager = $settingsManager ?? new SettingsManager(new ProjectSettings());
}
/** @return DocumentNode[] */
@@ -98,17 +106,20 @@ private function getDirectoryIndexFile(
$hashedContentFromFilesystem[$itemFromFilesystem['basename']] = true;
}
- foreach (self::INDEX_FILE_NAMES as $indexName) {
- $indexFilename = sprintf('%s.%s', $indexName, $extension);
- if (isset($hashedContentFromFilesystem[$indexFilename])) {
+ $indexFileNames = array_map('trim', explode(',', $this->settingsManager->getProjectSettings()->getIndexName()));
+
+ $indexNamesNotFound = [];
+ foreach ($indexFileNames as $indexName) {
+ $fullIndexFilename = sprintf('%s.%s', $indexName, $extension);
+ if (isset($hashedContentFromFilesystem[$fullIndexFilename])) {
return $indexName;
}
- }
- $indexFilename = sprintf('%s.%s', self::INDEX_FILE_NAMES[0], $extension);
+ $indexNamesNotFound[] = $fullIndexFilename;
+ }
throw new InvalidArgumentException(
- sprintf('Could not find index file "%s" in "%s"', $indexFilename, $directory),
+ sprintf('Could not find an index file "%s", expected file names: %s', $directory, implode(', ', $indexNamesNotFound)),
);
}
}
diff --git a/packages/guides/src/Settings/ProjectSettings.php b/packages/guides/src/Settings/ProjectSettings.php
index 84b5272a5..1256ac701 100644
--- a/packages/guides/src/Settings/ProjectSettings.php
+++ b/packages/guides/src/Settings/ProjectSettings.php
@@ -24,6 +24,7 @@ final class ProjectSettings
private string $theme = 'default';
private string $input = 'docs';
private string $inputFile = '';
+ private string $indexName = 'index,Index';
private string $output = 'output';
private string $inputFormat = 'rst';
/** @var string[] */
@@ -230,4 +231,16 @@ public function setIgnoredDomains(array $ignoredDomains): void
{
$this->ignoredDomains = $ignoredDomains;
}
+
+ public function getIndexName(): string
+ {
+ return $this->indexName;
+ }
+
+ public function setIndexName(string $indexName): ProjectSettings
+ {
+ $this->indexName = $indexName;
+
+ return $this;
+ }
}
diff --git a/tests/Integration/tests/markdown/index-name-md/expected/anotherPage.html b/tests/Integration/tests/markdown/index-name-md/expected/anotherPage.html
new file mode 100644
index 000000000..49c0fd5c5
--- /dev/null
+++ b/tests/Integration/tests/markdown/index-name-md/expected/anotherPage.html
@@ -0,0 +1,8 @@
+
+
+
Another Page
+
+
Lorem Ipsum Dolor.
+
+
+
Sample Markdown Document
+
+
Lorem Ipsum
+
+
+
Yet Another Page
+
+
Lorem Ipsum Dolor.
+
+