it is now possible to change the format of url link procuded in the m…

…arkdown via Markdown.UrlFormat configuration (closes #107)

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.
 
+<a name='MarkdownConfiguration_UrlFormat'></a>
+## 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}')`.
+
 <a name='Samples'></a>
 # Samples
 - [DefaultDocumentation api](https://github.com/Doraku/DefaultDocumentation/blob/master/documentation/api/index.md)

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
 

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;
     }
 
+    /// <summary>
+    /// Appends a formatted string to a <see cref="IWriter"/>.
+    /// </summary>
+    /// <param name="writer">The <see cref="IWriter"/> to append to.</param>
+    /// <param name="format">The format to use.</param>
+    /// <param name="args">The arguments to use in the format.</param>
+    /// <returns>The given <see cref="IWriter"/>.</returns>
+    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));
+    }
+
     /// <summary>
     /// Appends a line after writing the provided <see cref="string"/>.
     /// </summary>

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";
 
     /// <summary>
     /// Gets the current item that is being processed by this <see cref="IWriter"/>.
@@ -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;
     }
 
     /// <summary>
@@ -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;
+    }
+
+    /// <summary>
+    /// Gets the format that will be used to display urls.<br/>
+    /// </summary>
+    /// <remarks>
+    /// Three arguments will be passed to the format:
+    /// <list type="number">
+    ///     <item>the displayed text</item>
+    ///     <item>the url</item>
+    ///     <item>the tooltip to display when overing the link. If null the url will be used</item>
+    /// </list>
+    /// The default value is <c>[{0}]({1} '{2}')</c>.
+    /// </remarks>
+    /// <param name="writer">The <see cref="IWriter"/> for which to get this setting.</param>
+    /// <returns>Whether line break in the xml documentation should be handled in the generated markdown.</returns>
+    /// <seealso href="https://github.com/Doraku/DefaultDocumentation#MarkdownConfiguration_UrlFormat">Markdown.UrlFormat</seealso>
+    public static string GetUrlFormat(this IWriter writer)
+    {
+        writer.ThrowIfNull();
+
+        return writer.Context[_urlFormatKey] as string ?? "[{0}]({1} '{2}')";
+    }
+
+    /// <summary>
+    /// Sets the format that will be used to display url.
+    /// </summary>
+    /// <param name="writer">The <see cref="IWriter"/> for which to set this setting.</param>
+    /// <param name="value">The format to use to display urls.</param>
+    /// <returns>The given <see cref="IWriter"/>.</returns>
+    /// <seealso href="https://github.com/Doraku/DefaultDocumentation#MarkdownConfiguration_UrlFormat">Markdown.UrlFormat</seealso>
+    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());
             }
         }