diff --git a/cmf-cli/Handlers/PackageType/HelpMkDocsPackageTypeHandler.cs b/cmf-cli/Handlers/PackageType/HelpMkDocsPackageTypeHandler.cs
index e8dbd166b..2d5ced54a 100644
--- a/cmf-cli/Handlers/PackageType/HelpMkDocsPackageTypeHandler.cs
+++ b/cmf-cli/Handlers/PackageType/HelpMkDocsPackageTypeHandler.cs
@@ -33,7 +33,7 @@ public HelpMkDocsPackageTypeHandler(CmfPackage cmfPackage) : base(cmfPackage)
{
new Step(StepType.DeployFiles)
{
- ContentPath = "site/**",
+ ContentPath = "**",
TargetDirectory = "/"
}
}
@@ -105,6 +105,30 @@ public HelpMkDocsPackageTypeHandler(CmfPackage cmfPackage) : base(cmfPackage)
];
}
+ ///
+ internal override List GetContentToPack(IDirectoryInfo packageOutputDir)
+ {
+ var files = base.GetContentToPack(packageOutputDir);
+ var siteDirectory = fileSystem.Path.Join(CmfPackage.GetFileInfo().Directory.FullName, "site");
+
+ foreach (var file in files)
+ {
+ var relativePath = fileSystem.Path.GetRelativePath(siteDirectory, file.Source.FullName);
+ if (fileSystem.Path.IsPathRooted(relativePath)
+ || relativePath == ".."
+ || relativePath.StartsWith(".." + fileSystem.Path.DirectorySeparatorChar, StringComparison.Ordinal))
+ {
+ continue;
+ }
+
+ // DeployFiles preserves archive paths. Remove only the build output wrapper,
+ // keeping links between pages, assets and search files unchanged.
+ file.Target = fileSystem.FileInfo.New(fileSystem.Path.Join(packageOutputDir.FullName, relativePath));
+ }
+
+ return files;
+ }
+
///
/// Packs the generated MkDocs site.
///
@@ -151,7 +175,7 @@ public override void RestoreDependencies(Uri[] repoUris)
if (temporaryFolderForUnziping.Exists)
{
- // Each restored mkdocs zip unpacks site, docs and manifest.
+ // Each restored MkDocs zip contains the website, docs and manifest.
// We only care about the docs folder
var dependencyDocsFolders = fileSystem.Directory.GetDirectories(temporaryFolderForUnziping.FullName, "docs", SearchOption.AllDirectories);
diff --git a/cmf-cli/resources/template_feed/help/from1200/Help.Package/cmfpackage.json b/cmf-cli/resources/template_feed/help/from1200/Help.Package/cmfpackage.json
index fc2137fcf..22cd7c57a 100644
--- a/cmf-cli/resources/template_feed/help/from1200/Help.Package/cmfpackage.json
+++ b/cmf-cli/resources/template_feed/help/from1200/Help.Package/cmfpackage.json
@@ -9,7 +9,7 @@
"contentToPack": [
{
"source": "site/**",
- "target": "site"
+ "target": ""
},
{
"source": "docs/<%= $CLI_PARAM_ProjectName %>/**",
diff --git a/docs/src/03-explore/commands/pack.md b/docs/src/03-explore/commands/pack.md
index 514be2c5c..73a37641c 100644
--- a/docs/src/03-explore/commands/pack.md
+++ b/docs/src/03-explore/commands/pack.md
@@ -60,3 +60,20 @@ Name | Description
+
+## MES v12 MkDocs Help packages
+
+`cmf build` keeps MkDocs output in `site/`. When packing a v12 Help package,
+`cmf pack` places the selected contents of `site/` at the archive root, preserving
+all relative paths between HTML pages, assets and search files. Documentation
+sources remain under `docs//` for dependency restoration.
+
+This also applies to existing packages whose `contentToPack` maps `site/**` to
+`site`; no project-specific name or source configuration change is required.
+New Help templates map `site/**` to an empty target explicitly.
+
+The default `DeployFiles` step uses `contentPath: "**"`, so extraction into
+`/app` produces `/app/index.html`, matching the Product Help nginx configuration.
+This step also includes the packaged documentation sources. If you override the
+default steps, update any `site/**` filters to match the new archive layout.
+Help packages for MES versions before v12 retain their existing behavior.
diff --git a/tests/Specs/Pack.cs b/tests/Specs/Pack.cs
index 4e0330248..6eab30b02 100644
--- a/tests/Specs/Pack.cs
+++ b/tests/Specs/Pack.cs
@@ -1374,8 +1374,11 @@ public void Help_v12_MkDocsPack_FailsWhenSiteWasNotBuilt()
exception.Message.Should().Contain("Could not find MkDocs site");
}
- [Fact]
- public void Help_v12_MkDocsPack_SucceedsWhenSiteAndDocsExist()
+ [Theory]
+ [InlineData("site")]
+ [InlineData("")]
+ [InlineData("site/features/custom-feature")]
+ public void Help_v12_MkDocsPack_SucceedsWhenSiteAndDocsExist(string siteTarget)
{
var fileSystem = new MockFileSystem(new Dictionary
{
@@ -1387,21 +1390,25 @@ public void Help_v12_MkDocsPack_SucceedsWhenSiteAndDocsExist()
""version"": ""1.0.0"",
""packageType"": ""Help"",
""contentToPack"": [
- { ""source"": ""site/**"", ""target"": ""site"" },
+ { ""source"": ""site/**"", ""target"": """ + siteTarget + @""" },
{ ""source"": ""docs/cmf/**"", ""target"": ""docs/cmf"" }
]
}") },
{ "/repo/Cmf.Custom.Help/docs/requirements.txt", new MockFileData("mkdocs-material") },
{ "/repo/Cmf.Custom.Help/docs/cmf/index.md", new MockFileData("# Help") },
- { "/repo/Cmf.Custom.Help/site/index.html", new MockFileData("Help") },
- { "/repo/Cmf.Custom.Help/site/search/search_index.json", new MockFileData("{}") },
+ { "/repo/Cmf.Custom.Help/site/index.html", new MockFileData("Guide") },
+ { "/repo/Cmf.Custom.Help/site/search/search_index.json", new MockFileData("{\"docs\":[{\"location\":\"guide/\",\"title\":\"Guide\"}]}") },
+ { "/repo/Cmf.Custom.Help/site/guide/index.html", new MockFileData("Home") },
+ { "/repo/Cmf.Custom.Help/site/assets/theme.css", new MockFileData("body { background: url(images/icon.svg); }") },
+ { "/repo/Cmf.Custom.Help/site/assets/images/icon.svg", new MockFileData("") },
+ { "/repo/Cmf.Custom.Help/site/assets/search.js", new MockFileData("fetch('search/search_index.json')") },
{ "/repo/output", new MockDirectoryData() }
});
ExecutionContext.Initialize(fileSystem);
var packageTypeHandler = PackageTypeFactory.GetPackageTypeHandler(
- fileSystem.FileInfo.New("/repo/Cmf.Custom.Help/cmfpackage.json")) as HelpMkDocsPackageTypeHandler;
+ fileSystem.FileInfo.New("/repo/Cmf.Custom.Help/cmfpackage.json"), setDefaultValues: true) as HelpMkDocsPackageTypeHandler;
packageTypeHandler.Pack(
fileSystem.DirectoryInfo.New("/repo/package"),
@@ -1411,9 +1418,28 @@ public void Help_v12_MkDocsPack_SucceedsWhenSiteAndDocsExist()
packageZip.Exists.Should().BeTrue("Package zip file should be created");
using var zip = new ZipArchive(packageZip.OpenRead(), ZipArchiveMode.Read);
- zip.GetEntry("site/index.html").Should().NotBeNull();
+ zip.GetEntry("index.html").Should().NotBeNull();
+ zip.GetEntry("site/index.html").Should().BeNull();
zip.GetEntry("docs/cmf/index.md").Should().NotBeNull();
- zip.GetEntry("site/search/search_index.json").Should().NotBeNull();
+ zip.GetEntry("search/search_index.json").Should().NotBeNull();
+
+ // Keep every generated file byte-for-byte, preserving relative links and search locations.
+ foreach (var source in fileSystem.Directory.GetFiles("/repo/Cmf.Custom.Help/site", "*", SearchOption.AllDirectories))
+ {
+ var relativePath = fileSystem.Path.GetRelativePath("/repo/Cmf.Custom.Help/site", source).Replace('\\', '/');
+ var entry = zip.GetEntry(relativePath);
+ entry.Should().NotBeNull();
+ using var reader = new StreamReader(entry.Open());
+ reader.ReadToEnd().Should().Be(fileSystem.File.ReadAllText(source));
+ }
+
+ using var manifestReader = new StreamReader(zip.GetEntry("manifest.xml").Open());
+ var manifest = XDocument.Parse(manifestReader.ReadToEnd());
+ var step = manifest.Descendants("step").Single(e => (string)e.Attribute("type") == "DeployFiles");
+ ((string)step.Attribute("contentPath")).Should().Be("**");
+ ((string)step.Attribute("targetDirectory")).Should().Be("/");
+ fileSystem.File.ReadAllText("/repo/Cmf.Custom.Help/cmfpackage.json").Should().Contain("\"target\": \"" + siteTarget + "\"");
+
}
diff --git a/tests/Specs/Restore.cs b/tests/Specs/Restore.cs
index 358433243..93da38190 100644
--- a/tests/Specs/Restore.cs
+++ b/tests/Specs/Restore.cs
@@ -7,6 +7,7 @@
using System.IO.Abstractions.TestingHelpers;
using Cmf.CLI.Core.Services;
using Microsoft.Extensions.DependencyInjection;
+using Moq;
using tests.Objects;
using Xunit;
using Assert = tests.AssertWithMessage;
@@ -201,8 +202,23 @@ public void RestoreDependencies_RepoNotFound()
logWriter.ToString().Should().Contain("No present remote dependencies to restore. Exiting...");
}
- [Fact]
- public void RestoreDependencies_HelpMkDocs()
+ [Theory]
+ [InlineData(false)]
+ [InlineData(true)]
+ public void RestoreDependencies_HelpMkDocs(bool useRepositoryClients)
+ {
+ var previousServiceProvider = ExecutionContext.ServiceProvider;
+ try
+ {
+ RestoreDependencies_HelpMkDocsInternal(useRepositoryClients);
+ }
+ finally
+ {
+ ExecutionContext.ServiceProvider = previousServiceProvider;
+ }
+ }
+
+ private void RestoreDependencies_HelpMkDocsInternal(bool useRepositoryClients)
{
var gitRepo = MockUnixSupport.Path(@"c:\test");
var ciRepo = MockUnixSupport.Path(@"c:\cirepo");
@@ -234,13 +250,19 @@ public void RestoreDependencies_HelpMkDocs()
}") },
{ $"{gitRepo}/requirements.txt", new MockFileData("mkdocs") },
{ $"{gitRepo}/docs/other.txt", new MockFileData("original other") },
+ { $"{gitRepo}/docs/LocalProject/index.md", new MockFileData("# Local project documentation") },
{ $"{gitRepo}/docs/MyProject/old-file.txt", new MockFileData("old content") },
{ $"{gitRepo}/docs/MyProject/index.html", new MockFileData("old index") },
{ $"{ciRepo}/Cmf.Custom.Help.1.0.0.zip", new MockFileData(new DFPackageBuilder()
.CreateEntry("manifest.xml", @"Cmf.Custom.Help1.0.0")
+ .CreateEntry("index.html", "generated website")
+ .CreateEntry("assets/theme.css", "body {}")
+ .CreateEntry("search/search_index.json", "{}")
.CreateEntry("docs/MyProject/index.html", "index")
.CreateEntry("docs/MyProject/getting-started.html", "getting started")
.CreateEntry("docs/MyProject/reference.md", "# Reference")
+ .CreateEntry("docs/Features/OtherFeature/index.md", "# Feature documentation")
+ .CreateEntry("docs/Features/OtherFeature/assets/diagram.svg", "")
.CreateEntry("docs/other.txt", "restored other")
.CreateEntry("docs/assets/icon.png", "icon data")
.ToByteArray()) }
@@ -248,6 +270,7 @@ public void RestoreDependencies_HelpMkDocs()
ExecutionContext.ServiceProvider = new ServiceCollection()
.AddSingleton(new ProjectConfigService())
+ .AddSingleton(Mock.Of(features => features.UseRepositoryClients == useRepositoryClients))
.AddSingleton()
.BuildServiceProvider();
@@ -258,7 +281,13 @@ public void RestoreDependencies_HelpMkDocs()
var handler = PackageTypeFactory.GetPackageTypeHandler(package, false);
handler.Should().BeOfType();
- var repo = new UriBuilder { Scheme = Uri.UriSchemeFile, Host = "", Path = ciRepo }.Uri;
+ var repositoryPath = useRepositoryClients ? $"{ciRepo}/Cmf.Custom.Help.1.0.0.zip" : ciRepo;
+ var repo = new UriBuilder { Scheme = Uri.UriSchemeFile, Host = "", Path = repositoryPath }.Uri;
+ if (useRepositoryClients)
+ {
+ ExecutionContext.ServiceProvider.GetRequiredService()
+ .InitializeClientsForRepositories(fileSystem, new[] { repo });
+ }
handler.RestoreDependencies(new[] { repo });
@@ -272,10 +301,25 @@ public void RestoreDependencies_HelpMkDocs()
Assert.Equal("getting started", fileSystem.FileInfo.New($"{docs}/getting-started.html").OpenText().ReadToEnd());
Assert.Equal("# Reference", fileSystem.FileInfo.New($"{docs}/reference.md").OpenText().ReadToEnd());
+ Assert.Equal("# Feature documentation", fileSystem.File.ReadAllText($"{gitRepo}/docs/Features/OtherFeature/index.md"));
+ Assert.Equal("", fileSystem.File.ReadAllText($"{gitRepo}/docs/Features/OtherFeature/assets/diagram.svg"));
+ Assert.Equal("# Local project documentation", fileSystem.File.ReadAllText($"{gitRepo}/docs/LocalProject/index.md"));
+
+ // Repeated restores refresh the dependency tree while preserving local project sources.
+ fileSystem.File.WriteAllText($"{docs}/obsolete.md", "stale dependency page");
+ handler.RestoreDependencies(new[] { repo });
+ Assert.False(fileSystem.File.Exists($"{docs}/obsolete.md"), "Stale dependency pages should be removed");
+ Assert.Equal("# Reference", fileSystem.File.ReadAllText($"{docs}/reference.md"));
+ Assert.Equal("# Local project documentation", fileSystem.File.ReadAllText($"{gitRepo}/docs/LocalProject/index.md"));
+ Assert.Equal("# Feature documentation", fileSystem.File.ReadAllText($"{gitRepo}/docs/Features/OtherFeature/index.md"));
+
// Verify files outside docs/tenant were not touched or restored
Assert.True(fileSystem.FileInfo.New(MockUnixSupport.Path($@"{gitRepo}\docs\other.txt")).Exists, "File outside docs/tenant was removed");
Assert.Equal("original other", fileSystem.FileInfo.New(MockUnixSupport.Path($@"{gitRepo}\docs\other.txt")).OpenText().ReadToEnd());
Assert.False(fileSystem.FileInfo.New(MockUnixSupport.Path($@"{gitRepo}\docs\assets\icon.png")).Exists, "Assets folder should not be restored");
+ Assert.False(fileSystem.File.Exists($"{gitRepo}/docs/index.html"), "Generated home page should not be restored as a source");
+ Assert.False(fileSystem.Directory.Exists($"{gitRepo}/docs/search"), "Generated search files should not be restored");
+ Assert.False(fileSystem.File.Exists($"{gitRepo}/docs/assets/theme.css"), "Generated assets should not be restored");
}
}
}
\ No newline at end of file