Gate .mkdocsignore on file-filter enabled state

ContentDiscovery applied `.mkdocsignore` unconditionally, so dev-only
sections (e.g. listed for production exclusion) were hidden on every
build, including development and serve. This mirrors the mkdocs
behaviour where `.mkdocsignore` is owned by the file-filter plugin and
only prunes content when the filter is enabled.

- Add FileFilterSettings: a shared loader for `.file-filter.yml` that
  resolves enabled/enabled_on_serve (with !ENV support) plus the
  mkdocsignore + label-filter options, exposing IsActive,
  AppliesMkdocsIgnore and AppliesLabelFilter.
- IgnoreRules.Load now takes includeIgnoreFile / ignoreFileName so the
  ignore file can be skipped while config `exclude` globs stay always-on.
- ContentDiscovery takes BuildOptions and only applies the ignore file
  when the filter is active for the current mode. No `.file-filter.yml`
  keeps the ignore file always-on (backward compatible, gitignore-like).
- FileFilterPlugin reuses FileFilterSettings so label pruning and
  path pruning share one enabled gate.
- Add FileFilterTests covering settings resolution and a dev-vs-prod
  discovery integration test.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: Netdocs

src/Netdocs.Core/BuildEngine.cs

@@ -55,7 +55,7 @@ public async Task<SiteContext> BuildAsync(CancellationToken ct = default)
         List<Page> pages;
         using (Measure("1. content discovery"))
         {
-            var discovery = new ContentDiscovery(config, loggerFactory.CreateLogger<ContentDiscovery>());
+            var discovery = new ContentDiscovery(config, options, loggerFactory.CreateLogger<ContentDiscovery>());
             pages = discovery.Discover().ToList();
         }
 

src/Netdocs.Core/Content/ContentDiscovery.cs

@@ -4,7 +4,7 @@
 namespace Netdocs.Core.Content;
 
 /// <summary>Walks the docs directory and produces <see cref="Page"/> instances.</summary>
-public sealed class ContentDiscovery(SiteConfig config, ILogger<ContentDiscovery> logger)
+public sealed class ContentDiscovery(SiteConfig config, BuildOptions options, ILogger<ContentDiscovery> logger)
 {
     private static readonly string[] MarkdownExtensions = [".md", ".markdown"];
 
@@ -14,7 +14,11 @@ public IReadOnlyList<Page> Discover()
         if (!Directory.Exists(docsDir))
             throw new DirectoryNotFoundException($"docs_dir not found: {docsDir}");
 
-        var ignore = IgnoreRules.Load(config.ProjectRoot, docsDir, config.Exclude);
+        // `.mkdocsignore` only prunes content when the file-filter is active for this build mode
+        // (production, by default). On dev / serve builds the listed dev-only sections stay in.
+        var filter = FileFilterSettings.Load(config.ProjectRoot);
+        var applyIgnoreFile = filter.AppliesMkdocsIgnore(options.IsServe);
+        var ignore = IgnoreRules.Load(config.ProjectRoot, docsDir, config.Exclude, applyIgnoreFile, filter.MkdocsignoreFile);
         var pages = new List<Page>();
 
         foreach (var file in Directory.EnumerateFiles(docsDir, "*", SearchOption.AllDirectories))

src/Netdocs.Core/Content/FileFilterSettings.cs

@@ -0,0 +1,74 @@
+using Netdocs.Core.Configuration;
+
+namespace Netdocs.Core.Content;
+
+/// <summary>
+/// Reads <c>.file-filter.yml</c> (mkdocs-file-filter compatible) from the project root and
+/// resolves whether content filtering is active for the current build mode.
+///
+/// The whole filter — front-matter label pruning AND <c>.mkdocsignore</c> path exclusion — is
+/// gated behind <c>enabled</c> / <c>enabled_on_serve</c> (both support <c>!ENV</c> lookups, which
+/// <see cref="YamlTree"/> resolves at parse time). This lets a development or <c>serve</c> build
+/// keep draft / dev-only content that a production build hides, matching the upstream plugin.
+///
+/// When no <c>.file-filter.yml</c> exists, a <c>.mkdocsignore</c> is treated as an always-on
+/// ignore file (like <c>.gitignore</c>) so simple projects that never opted into the filter keep
+/// their previous behaviour.
+/// </summary>
+public sealed class FileFilterSettings
+{
+    public bool Exists { get; private init; }
+    public bool Enabled { get; private init; } = true;
+    public bool EnabledOnServe { get; private init; } = true;
+    public bool Mkdocsignore { get; private init; } = true;
+    public string MkdocsignoreFile { get; private init; } = ".mkdocsignore";
+    public string MetadataProperty { get; private init; } = "labels";
+    public IReadOnlySet<string> ExcludeTags { get; private init; } = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
+    public IReadOnlySet<string> IncludeTags { get; private init; } = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
+
+    public static FileFilterSettings Load(string projectRoot)
+    {
+        var path = Path.Combine(projectRoot, ".file-filter.yml");
+        if (!File.Exists(path))
+            return new FileFilterSettings { Exists = false };
+
+        var root = YamlTree.Parse(File.ReadAllText(path)).AsMap();
+
+        var excludeTags = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
+        foreach (var t in root.Get("exclude_tag").AsList())
+            if (t.AsString() is { Length: > 0 } s) excludeTags.Add(s);
+
+        var includeTags = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
+        foreach (var t in root.Get("include_tag").AsList())
+            if (t.AsString() is { Length: > 0 } s) includeTags.Add(s);
+
+        var file = root.Get("mkdocsignore_file").AsString();
+        var prop = root.Get("metadata_property").AsString();
+
+        return new FileFilterSettings
+        {
+            Exists = true,
+            Enabled = root.Get("enabled").AsBool(true),
+            EnabledOnServe = root.TryGetValue("enabled_on_serve", out var eos) ? eos.AsBool(true) : true,
+            Mkdocsignore = root.Get("mkdocsignore").AsBool(true),
+            MkdocsignoreFile = string.IsNullOrWhiteSpace(file) ? ".mkdocsignore" : file!,
+            MetadataProperty = prop is { Length: > 0 } ? prop : "labels",
+            ExcludeTags = excludeTags,
+            IncludeTags = includeTags,
+        };
+    }
+
+    /// <summary>Whether the filter runs at all for this build (the <c>enabled</c> gate).</summary>
+    public bool IsActive(bool isServe) =>
+        Exists && (isServe ? Enabled && EnabledOnServe : Enabled);
+
+    /// <summary>Whether label-based pruning runs (the gate AND at least one <c>exclude_tag</c>).</summary>
+    public bool AppliesLabelFilter(bool isServe) => IsActive(isServe) && ExcludeTags.Count > 0;
+
+    /// <summary>
+    /// Whether <c>.mkdocsignore</c> path rules should be applied for this build. With no filter
+    /// config the ignore file is always honoured; otherwise it follows the <c>enabled</c> gate so
+    /// dev-only sections listed there reappear on non-production builds.
+    /// </summary>
+    public bool AppliesMkdocsIgnore(bool isServe) => !Exists || (Mkdocsignore && IsActive(isServe));
+}

src/Netdocs.Core/Content/IgnoreRules.cs

@@ -9,12 +9,24 @@ public sealed partial class IgnoreRules
 
     private IgnoreRules(List<Regex> patterns) => _patterns = patterns;
 
-    public static IgnoreRules Load(string projectRoot, string docsDir)
+    /// <param name="includeIgnoreFile">
+    /// When true, patterns from the <paramref name="ignoreFileName"/> file (default
+    /// <c>.mkdocsignore</c>) are loaded. Callers pass false to skip it — e.g. a development build
+    /// where the file-filter is disabled — so dev-only sections listed there stay in the site.
+    /// </param>
+    /// <param name="ignoreFileName">Name of the ignore file to read (from docs dir, then project root).</param>
+    public static IgnoreRules Load(
+        string projectRoot,
+        string docsDir,
+        IEnumerable<string> extraPatterns,
+        bool includeIgnoreFile = true,
+        string ignoreFileName = ".mkdocsignore")
     {
         var patterns = new List<Regex>();
-        foreach (var name in new[] { ".mkdocsignore" })
+
+        if (includeIgnoreFile)
         {
-            foreach (var path in new[] { Path.Combine(docsDir, name), Path.Combine(projectRoot, name) })
+            foreach (var path in new[] { Path.Combine(docsDir, ignoreFileName), Path.Combine(projectRoot, ignoreFileName) })
             {
                 if (!File.Exists(path)) continue;
                 foreach (var line in File.ReadAllLines(path))
@@ -25,18 +37,15 @@ public static IgnoreRules Load(string projectRoot, string docsDir)
                 }
             }
         }
-        return new IgnoreRules(patterns);
-    }
 
-    public static IgnoreRules Load(string projectRoot, string docsDir, IEnumerable<string> extraPatterns)
-    {
-        var rules = Load(projectRoot, docsDir);
+        // Explicit config `exclude` globs are always honoured, independent of the ignore file.
         foreach (var pattern in extraPatterns)
         {
             var trimmed = pattern.Trim();
-            if (trimmed.Length > 0) rules._patterns.Add(GlobToRegex(trimmed));
+            if (trimmed.Length > 0) patterns.Add(GlobToRegex(trimmed));
         }
-        return rules;
+
+        return new IgnoreRules(patterns);
     }
 
     public bool IsIgnored(string relativePath)

src/Netdocs.Plugins/StubPlugins.cs

@@ -1,6 +1,7 @@
 using Markdig;
 using Netdocs.Abstractions;
 using Netdocs.Core.Configuration;
+using Netdocs.Core.Content;
 
 namespace Netdocs.Plugins;
 
@@ -21,22 +22,15 @@ public sealed class FileFilterPlugin : IPlugin, INavigationFilter
 
     public void Configure(IPluginContext ctx)
     {
-        var path = Path.Combine(ctx.Config.ProjectRoot, ".file-filter.yml");
-        if (!File.Exists(path)) { _active = false; return; }
-
-        var root = YamlTree.Parse(File.ReadAllText(path)).AsMap();
-
-        var enabled = root.Get("enabled").AsBool(true);
-        var enabledOnServe = root.TryGetValue("enabled_on_serve", out var eos) ? eos.AsBool(true) : true;
-        _active = ctx.Options.IsServe ? enabled && enabledOnServe : enabled;
-
-        if (root.Get("metadata_property").AsString() is { Length: > 0 } prop) _metadataProperty = prop;
-        foreach (var t in root.Get("exclude_tag").AsList())
-            if (t.AsString() is { Length: > 0 } s) _excludeTags.Add(s);
-        foreach (var t in root.Get("include_tag").AsList())
-            if (t.AsString() is { Length: > 0 } s) _includeTags.Add(s);
-
-        if (_excludeTags.Count == 0) _active = false;
+        // Path-based `.mkdocsignore` pruning is handled during content discovery; this plugin owns
+        // the front-matter label filter. Both share the same enabled gate via FileFilterSettings.
+        var settings = FileFilterSettings.Load(ctx.Config.ProjectRoot);
+        _active = settings.AppliesLabelFilter(ctx.Options.IsServe);
+        if (!_active) return;
+
+        _metadataProperty = settings.MetadataProperty;
+        foreach (var t in settings.ExcludeTags) _excludeTags.Add(t);
+        foreach (var t in settings.IncludeTags) _includeTags.Add(t);
     }
 
     public bool ShouldInclude(Page page, SiteContext site)

tests/Netdocs.Core.Tests/FileFilterTests.cs

@@ -0,0 +1,145 @@
+using Microsoft.Extensions.Logging.Abstractions;
+using Netdocs.Abstractions;
+using Netdocs.Core.Content;
+using Xunit;
+
+namespace Netdocs.Core.Tests;
+
+/// <summary>
+/// Covers <see cref="FileFilterSettings"/> resolution and the gating of <c>.mkdocsignore</c> in
+/// <see cref="ContentDiscovery"/>. The key behaviour: dev-only sections listed in
+/// <c>.mkdocsignore</c> stay in non-production builds and disappear only when the file-filter is
+/// enabled (production).
+/// </summary>
+public class FileFilterTests : IDisposable
+{
+    private readonly string _root;
+
+    public FileFilterTests()
+    {
+        _root = Path.Combine(Path.GetTempPath(), "ndfilter-" + Guid.NewGuid().ToString("N"));
+        Directory.CreateDirectory(Path.Combine(_root, "docs"));
+    }
+
+    public void Dispose()
+    {
+        try { Directory.Delete(_root, recursive: true); } catch { /* best effort */ }
+    }
+
+    private void WriteFilter(string yaml) => File.WriteAllText(Path.Combine(_root, ".file-filter.yml"), yaml);
+
+    // ---- FileFilterSettings unit behaviour -------------------------------------------------
+
+    [Fact]
+    public void NoConfig_IgnoreFileAlwaysApplies_FilterInactive()
+    {
+        var s = FileFilterSettings.Load(_root);
+
+        Assert.False(s.Exists);
+        Assert.False(s.IsActive(isServe: false));
+        Assert.True(s.AppliesMkdocsIgnore(isServe: false));   // backward compatible: honored
+        Assert.True(s.AppliesMkdocsIgnore(isServe: true));
+        Assert.False(s.AppliesLabelFilter(isServe: false));
+    }
+
+    [Fact]
+    public void EnabledFalse_IgnoreFileSkipped()
+    {
+        WriteFilter("enabled: false\nmkdocsignore: true\n");
+        var s = FileFilterSettings.Load(_root);
+
+        Assert.True(s.Exists);
+        Assert.False(s.IsActive(isServe: false));
+        Assert.False(s.AppliesMkdocsIgnore(isServe: false));
+    }
+
+    [Fact]
+    public void EnabledTrue_IgnoreFileApplied_OnBuild_ButNotServeWhenServeDisabled()
+    {
+        WriteFilter("enabled: true\nenabled_on_serve: false\nmkdocsignore: true\n");
+        var s = FileFilterSettings.Load(_root);
+
+        Assert.True(s.IsActive(isServe: false));      // production build
+        Assert.True(s.AppliesMkdocsIgnore(isServe: false));
+        Assert.False(s.IsActive(isServe: true));      // serve stays off
+        Assert.False(s.AppliesMkdocsIgnore(isServe: true));
+    }
+
+    [Fact]
+    public void EnvResolution_ProdBuildFlag_TogglesFilter()
+    {
+        WriteFilter("enabled: !ENV [MKDOCS_PROD_BUILD, false]\nmkdocsignore: true\n");
+
+        Environment.SetEnvironmentVariable("MKDOCS_PROD_BUILD", "false");
+        Assert.False(FileFilterSettings.Load(_root).AppliesMkdocsIgnore(isServe: false));
+
+        Environment.SetEnvironmentVariable("MKDOCS_PROD_BUILD", "true");
+        Assert.True(FileFilterSettings.Load(_root).AppliesMkdocsIgnore(isServe: false));
+
+        Environment.SetEnvironmentVariable("MKDOCS_PROD_BUILD", null);
+    }
+
+    [Fact]
+    public void LabelFilter_RequiresEnabledAndExcludeTags()
+    {
+        WriteFilter("enabled: true\nexclude_tag:\n  - draft\n");
+        Assert.True(FileFilterSettings.Load(_root).AppliesLabelFilter(isServe: false));
+
+        WriteFilter("enabled: true\n");   // no exclude tags
+        Assert.False(FileFilterSettings.Load(_root).AppliesLabelFilter(isServe: false));
+
+        WriteFilter("enabled: false\nexclude_tag:\n  - draft\n");
+        Assert.False(FileFilterSettings.Load(_root).AppliesLabelFilter(isServe: false));
+    }
+
+    // ---- ContentDiscovery integration ------------------------------------------------------
+
+    private void Seed()
+    {
+        var docs = Path.Combine(_root, "docs");
+        File.WriteAllText(Path.Combine(docs, "index.md"), "# Home\n");
+        Directory.CreateDirectory(Path.Combine(docs, "teams"));
+        File.WriteAllText(Path.Combine(docs, "teams", "index.md"), "# Teams\n");
+        File.WriteAllText(Path.Combine(_root, ".mkdocsignore"), "teams/\n");
+    }
+
+    private IReadOnlyList<Page> Discover(bool isProduction)
+    {
+        var config = new SiteConfig { ProjectRoot = _root, DocsDir = "docs" };
+        var options = new BuildOptions { IsProduction = isProduction, IsServe = false };
+        return new ContentDiscovery(config, options, NullLogger<ContentDiscovery>.Instance).Discover();
+    }
+
+    [Fact]
+    public void DevBuild_KeepsMkdocsIgnoredSection_WhenFilterDisabled()
+    {
+        Seed();
+        WriteFilter("enabled: false\nmkdocsignore: true\n");
+
+        var pages = Discover(isProduction: false);
+
+        Assert.Contains(pages, p => p.RelativePath.Replace('\\', '/') == "teams/index.md");
+    }
+
+    [Fact]
+    public void ProdBuild_HidesMkdocsIgnoredSection_WhenFilterEnabled()
+    {
+        Seed();
+        WriteFilter("enabled: true\nmkdocsignore: true\n");
+
+        var pages = Discover(isProduction: true);
+
+        Assert.DoesNotContain(pages, p => p.RelativePath.Replace('\\', '/') == "teams/index.md");
+        Assert.Contains(pages, p => p.RelativePath.Replace('\\', '/') == "index.md");
+    }
+
+    [Fact]
+    public void NoFilterConfig_HonorsMkdocsIgnore_LikeGitignore()
+    {
+        Seed();   // no .file-filter.yml
+
+        var pages = Discover(isProduction: false);
+
+        Assert.DoesNotContain(pages, p => p.RelativePath.Replace('\\', '/') == "teams/index.md");
+    }
+}