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());
}
}