Markdown.UrlFormat configuration is ignored in DefaultDocumentation 1.2.5

[transcendentalcat]

Markdown.UrlFormat configuration is ignored in DefaultDocumentation 1.2.5

Hi,

I am using DefaultDocumentation 1.2.5 to generate Markdown API documentation and encountered an issue with the documented Markdown.UrlFormat setting.

I would like generated links to use angle-bracketed destinations because some of our member anchors contain method signatures with parentheses and commas.

For example, instead of:

[TryGetParameterByName\(string, Parameter\)](Common.TestContract.md#.Common.TestContract.TryGetParameterByName(string,Parameters.Parameter) '...')

I would like to generate:

[TryGetParameterByName\(string, Parameter\)](<Common.TestContract.md#Common.TestContract.TryGetParameterByName(string,Parameters.Parameter)> '...')

According to the documentation, I expected this configuration to work:

"Markdown.UrlFormat": "[{0}](<{1}> '{2}')"

However, the setting appears to be ignored completely. The generated Markdown continues to use the default format:

[{0}]({1} '{2}')

I verified the following:

• The correct configuration file is loaded.
• Markdown.UrlFormat is present in the effective configuration printed by the console.
• Other Markdown settings from the same JSON file work correctly. For example:

"Markdown.RemoveFileExtensionFromUrl": true

is applied as expected.

• I reproduced the issue without any custom plugins or custom IUrlFactory implementations.
• Even an obvious test value such as:

"Markdown.UrlFormat": "URL_TEST[{0}](<{1}>)"

does not appear anywhere in the generated output.

I also investigated the DefaultDocumentation 1.2.5 implementation and found what seems to explain the behavior.

GetUrlFormat() appears to read the value only from the writer/page context:

public static string GetUrlFormat(this IWriter writer)
{
    return (writer.Context["Markdown.UrlFormat"] as string)
        ?? "[{0}]({1} '{2}')";
}

However, the JSON configuration is accessed through GetSetting<T>().

For comparison, Markdown.HandleLineBreak appears to check both the writer context and the configuration, while Markdown.UrlFormat does not.

There is also a public:

writer.SetUrlFormat(...)

method, but I could not find any code in DefaultDocumentation itself that calls it. This seems to mean that a value specified in DefaultDocumentation.json is never propagated into the writer context.

So my questions are:

1. Is Markdown.UrlFormat intended to be configurable directly from DefaultDocumentation.json in version 1.2.5?
2. Is the current behavior a bug, or am I missing an additional configuration/initialization step?
3. Is there an officially recommended way to apply Markdown.UrlFormat without adding a custom ISection?
4. If this is a bug, would changing GetUrlFormat() so that it falls back to the configured setting be the expected fix, for example:

return (writer.Context["Markdown.UrlFormat"] as string)
    ?? writer.Context.GetSetting(
        writer.GetCurrentItem(),
        context => context.GetSetting<string>("Markdown.UrlFormat"))
    ?? "[{0}]({1} '{2}')";

I would prefer to solve this at the Markdown rendering level rather than through a custom IUrlFactory, since changing the URL itself would also affect .links output and generated anchors.

Thanks in advance for any clarification or recommended solution.

[NotAFlightRisk]

I've had a go at fixing this in #297.

[transcendentalcat]

Thank you!

[Doraku]

Thanks for being faster that me @NotAFlightRisk, fixing what was definitely not the intended result.