diff --git a/README.md b/README.md index c2380cd2..e897b9f4 100644 --- a/README.md +++ b/README.md @@ -59,6 +59,7 @@ dotnet tool - [InvalidCharReplacement](#MarkdownConfiguration_InvalidCharReplacement) - [HandleLineBreak](#MarkdownConfiguration_HandleLineBreak) - [TableOfContentsModes](#MarkdownConfiguration_TableOfContentsModes) + - [Url format](#MarkdownConfiguration_UrlFormat) - [Samples](#Samples) - [Dependencies](#Dependencies) @@ -537,6 +538,19 @@ States how the table of contents should be rendered. Available values are: This setting can be overriden by specific `DocItem` types. + +## Url format +- configuration file: `"Markdown.UrlFormat": ""` + +State the format that will be used to display urls. + +Three arguments will be passed to the format: +- the displayed text +- the url +- the tooltip to display when overing the link. If null the url will be used + +The default value is `[{0}]({1} '{2}')`. + # Samples - [DefaultDocumentation api](https://github.com/Doraku/DefaultDocumentation/blob/master/documentation/api/index.md) diff --git a/documentation/NEXT_RELEASENOTES.txt b/documentation/NEXT_RELEASENOTES.txt index bf131628..9ef454e2 100644 --- a/documentation/NEXT_RELEASENOTES.txt +++ b/documentation/NEXT_RELEASENOTES.txt @@ -6,6 +6,7 @@ - added DefaultDocumentation.GeneratedAccessModifiers.Api which regroup Public, Protected and InternalProtected access modifiers (closes #116) - added support for record - elements, url factories, file name factory and sections are now case insensitive in configuration (closes #157) +- it is now possible to change the format of url link procuded in the markdown via Markdown.UrlFormat configuration (closes #107) ## Bug fixes diff --git a/source/DefaultDocumentation.Api/Extensions/IWriterExtensions.cs b/source/DefaultDocumentation.Api/Extensions/IWriterExtensions.cs index a7c7167c..d99c31bd 100644 --- a/source/DefaultDocumentation.Api/Extensions/IWriterExtensions.cs +++ b/source/DefaultDocumentation.Api/Extensions/IWriterExtensions.cs @@ -1,4 +1,5 @@ using System; +using System.Globalization; using System.Xml.Linq; namespace DefaultDocumentation.Api; @@ -87,6 +88,21 @@ static void AppendMultiline(IWriter writer, string text, ref int? textStartIndex return writer; } + /// + /// Appends a formatted string to a . + /// + /// The to append to. + /// The format to use. + /// The arguments to use in the format. + /// The given . + public static IWriter AppendFormat(this IWriter writer, string format, params object?[] args) + { + writer.ThrowIfNull(); + format.ThrowIfNull(); + + return writer.Append(string.Format(CultureInfo.InvariantCulture, format, args)); + } + /// /// Appends a line after writing the provided . /// diff --git a/source/DefaultDocumentation.Markdown/Extensions/IWriterExtensions.cs b/source/DefaultDocumentation.Markdown/Extensions/IWriterExtensions.cs index 7f258c86..9519c548 100644 --- a/source/DefaultDocumentation.Markdown/Extensions/IWriterExtensions.cs +++ b/source/DefaultDocumentation.Markdown/Extensions/IWriterExtensions.cs @@ -27,7 +27,8 @@ public static class IWriterExtensions private const string _currentItemKey = "Markdown.CurrentItem"; private const string _displayAsSingleLineKey = "Markdown.DisplayAsSingleLine"; private const string _handleLineBreakKey = "Markdown.HandleLineBreak"; - private const string _renderAsRaw = "Markdown.RenderAsRaw"; + private const string _renderAsRawKey = "Markdown.RenderAsRaw"; + private const string _urlFormatKey = "Markdown.UrlFormat"; /// /// Gets the current item that is being processed by this . @@ -130,7 +131,7 @@ public static bool GetRenderAsRaw(this IWriter writer) { writer.ThrowIfNull(); - return writer.Context[_renderAsRaw] as bool? ?? false; + return writer.Context[_renderAsRawKey] as bool? ?? false; } /// @@ -144,7 +145,45 @@ public static IWriter SetRenderAsRaw(this IWriter writer, bool? value) { writer.ThrowIfNull(); - writer.Context[_renderAsRaw] = value; + writer.Context[_renderAsRawKey] = value; + + return writer; + } + + /// + /// Gets the format that will be used to display urls.
+ ///
+ /// + /// Three arguments will be passed to the format: + /// + /// the displayed text + /// the url + /// the tooltip to display when overing the link. If null the url will be used + /// + /// The default value is [{0}]({1} '{2}'). + /// + /// The for which to get this setting. + /// Whether line break in the xml documentation should be handled in the generated markdown. + /// Markdown.UrlFormat + public static string GetUrlFormat(this IWriter writer) + { + writer.ThrowIfNull(); + + return writer.Context[_urlFormatKey] as string ?? "[{0}]({1} '{2}')"; + } + + /// + /// Sets the format that will be used to display url. + /// + /// The for which to set this setting. + /// The format to use to display urls. + /// The given . + /// Markdown.UrlFormat + public static IWriter SetUrlFormat(this IWriter writer, string? value) + { + writer.ThrowIfNull(); + + writer.Context[_urlFormatKey] = value; return writer; } @@ -185,14 +224,11 @@ public static IWriter AppendUrl(this IWriter writer, string? url, string? displa } else { - writer - .Append("[") - .Append((displayedName ?? url!).Prettify().SanitizeForMarkdown()) - .Append("](") - .Append(url!) - .Append(" '") - .Append((tooltip ?? url!).SanitizeForMarkdown()) - .Append("')"); + writer.AppendFormat( + writer.GetUrlFormat(), + (displayedName ?? url!).Prettify().SanitizeForMarkdown(), + url!, + (tooltip ?? url!).SanitizeForMarkdown()); } }