Merge pull request #21723 from bdach/wiki-heading-id-attributes

Add support for block attributes in wiki overlay

osu.Game.Tests/Visual/Online/TestSceneWikiMarkdownContainer.cs

@@ -19,6 +19,7 @@ using osu.Game.Graphics.Containers.Markdown;
 using osu.Game.Graphics.Containers.Markdown.Footnotes;
 using osu.Game.Overlays;
 using osu.Game.Overlays.Wiki.Markdown;
+using osu.Game.Users.Drawables;
 using osuTK.Input;
 
 namespace osu.Game.Tests.Visual.Online
@@ -210,6 +211,17 @@ Line after image";
                 markdownContainer.CurrentPath = @"https://dev.ppy.sh";
                 markdownContainer.Text = "::{flag=\"AU\"}:: ::{flag=\"ZZ\"}::";
             });
+            AddAssert("Two flags visible", () => markdownContainer.ChildrenOfType<DrawableFlag>().Count(), () => Is.EqualTo(2));
+        }
+
+        [Test]
+        public void TestHeadingWithIdAttribute()
+        {
+            AddStep("Add heading with ID", () =>
+            {
+                markdownContainer.Text = "# This is a heading with an ID {#this-is-the-id}";
+            });
+            AddAssert("ID not visible", () => markdownContainer.ChildrenOfType<SpriteText>().All(spriteText => spriteText.Text != "{#this-is-the-id}"));
         }
 
         [Test]

osu.Game/Graphics/Containers/Markdown/Extensions/BlockAttributeExtension.cs

@@ -0,0 +1,34 @@
+// Copyright (c) ppy Pty Ltd <contact@ppy.sh>. Licensed under the MIT Licence.
+// See the LICENCE file in the repository root for full licence text.
+
+using Markdig;
+using Markdig.Extensions.GenericAttributes;
+using Markdig.Renderers;
+using Markdig.Syntax;
+
+namespace osu.Game.Graphics.Containers.Markdown.Extensions
+{
+    /// <summary>
+    /// A variant of <see cref="Markdig.Extensions.GenericAttributes.GenericAttributesExtension"/>
+    /// which only handles generic attributes in the current markdown <see cref="Block"/> and ignores inline generic attributes.
+    /// </summary>
+    /// <remarks>
+    /// For rationale, see implementation of <see cref="Setup(Markdig.MarkdownPipelineBuilder)"/>.
+    /// </remarks>
+    public class BlockAttributeExtension : IMarkdownExtension
+    {
+        private readonly GenericAttributesExtension genericAttributesExtension = new GenericAttributesExtension();
+
+        public void Setup(MarkdownPipelineBuilder pipeline)
+        {
+            genericAttributesExtension.Setup(pipeline);
+
+            // GenericAttributesExtension registers a GenericAttributesParser in pipeline.InlineParsers.
+            // this conflicts with the CustomContainerExtension, leading to some custom containers (e.g. flags) not displaying.
+            // as a workaround, remove the inline parser here before it can do damage.
+            pipeline.InlineParsers.RemoveAll(parser => parser is GenericAttributesParser);
+        }
+
+        public void Setup(MarkdownPipeline pipeline, IMarkdownRenderer renderer) => genericAttributesExtension.Setup(pipeline, renderer);
+    }
+}

osu.Game/Graphics/Containers/Markdown/Extensions/OsuMarkdownExtensions.cs

@@ -0,0 +1,21 @@
+// Copyright (c) ppy Pty Ltd <contact@ppy.sh>. Licensed under the MIT Licence.
+// See the LICENCE file in the repository root for full licence text.
+
+using Markdig;
+
+namespace osu.Game.Graphics.Containers.Markdown.Extensions
+{
+    public static class OsuMarkdownExtensions
+    {
+        /// <summary>
+        /// Uses the block attributes extension.
+        /// </summary>
+        /// <param name="pipeline">The pipeline.</param>
+        /// <returns>The modified pipeline.</returns>
+        public static MarkdownPipelineBuilder UseBlockAttributes(this MarkdownPipelineBuilder pipeline)
+        {
+            pipeline.Extensions.AddIfNotAlready<BlockAttributeExtension>();
+            return pipeline;
+        }
+    }
+}

osu.Game/Graphics/Containers/Markdown/OsuMarkdownContainer.cs

@@ -4,9 +4,6 @@
 #nullable disable
 
 using Markdig;
-using Markdig.Extensions.AutoLinks;
-using Markdig.Extensions.CustomContainers;
-using Markdig.Extensions.EmphasisExtras;
 using Markdig.Extensions.Footnotes;
 using Markdig.Extensions.Tables;
 using Markdig.Extensions.Yaml;
@@ -26,24 +23,6 @@ namespace osu.Game.Graphics.Containers.Markdown
     [Cached]
     public partial class OsuMarkdownContainer : MarkdownContainer
     {
-        /// <summary>
-        /// Allows this markdown container to parse and link footnotes.
-        /// </summary>
-        /// <seealso cref="FootnoteExtension"/>
-        protected virtual bool Footnotes => false;
-
-        /// <summary>
-        /// Allows this markdown container to make URL text clickable.
-        /// </summary>
-        /// <seealso cref="AutoLinkExtension"/>
-        protected virtual bool Autolinks => false;
-
-        /// <summary>
-        /// Allows this markdown container to parse custom containers (used for flags and infoboxes).
-        /// </summary>
-        /// <seealso cref="CustomContainerExtension"/>
-        protected virtual bool CustomContainers => false;
-
         public OsuMarkdownContainer()
         {
             LineSpacing = 21;
@@ -108,25 +87,13 @@ namespace osu.Game.Graphics.Containers.Markdown
 
         protected override MarkdownFootnote CreateFootnote(Footnote footnote) => new OsuMarkdownFootnote(footnote);
 
-        // reference: https://github.com/ppy/osu-web/blob/05488a96b25b5a09f2d97c54c06dd2bae59d1dc8/app/Libraries/Markdown/OsuMarkdown.php#L301
-        protected override MarkdownPipeline CreateBuilder()
-        {
-            var pipeline = new MarkdownPipelineBuilder()
-                           .UseAutoIdentifiers()
-                           .UsePipeTables()
-                           .UseEmphasisExtras(EmphasisExtraOptions.Strikethrough)
-                           .UseYamlFrontMatter();
+        protected sealed override MarkdownPipeline CreateBuilder()
+            => Options.BuildPipeline();
 
-            if (Footnotes)
-                pipeline = pipeline.UseFootnotes();
-
-            if (Autolinks)
-                pipeline = pipeline.UseAutoLinks();
-
-            if (CustomContainers)
-                pipeline.UseCustomContainers();
-
-            return pipeline.Build();
-        }
+        /// <summary>
+        /// Creates a <see cref="OsuMarkdownContainerOptions"/> instance which is used to determine
+        /// which CommonMark/Markdig extensions should be enabled for this <see cref="OsuMarkdownContainer"/>.
+        /// </summary>
+        protected virtual OsuMarkdownContainerOptions Options => new OsuMarkdownContainerOptions();
     }
 }

osu.Game/Graphics/Containers/Markdown/OsuMarkdownContainerOptions.cs

@@ -0,0 +1,71 @@
+// Copyright (c) ppy Pty Ltd <contact@ppy.sh>. Licensed under the MIT Licence.
+// See the LICENCE file in the repository root for full licence text.
+
+using Markdig;
+using Markdig.Extensions.AutoLinks;
+using Markdig.Extensions.CustomContainers;
+using Markdig.Extensions.EmphasisExtras;
+using Markdig.Extensions.Footnotes;
+using osu.Game.Graphics.Containers.Markdown.Extensions;
+
+namespace osu.Game.Graphics.Containers.Markdown
+{
+    /// <summary>
+    /// Groups options of customising the set of available extensions to <see cref="OsuMarkdownContainer"/> instances.
+    /// </summary>
+    public class OsuMarkdownContainerOptions
+    {
+        /// <summary>
+        /// Allows the <see cref="OsuMarkdownContainer"/> to parse and link footnotes.
+        /// </summary>
+        /// <seealso cref="FootnoteExtension"/>
+        public bool Footnotes { get; init; }
+
+        /// <summary>
+        /// Allows the <see cref="OsuMarkdownContainer"/> container to make URL text clickable.
+        /// </summary>
+        /// <seealso cref="AutoLinkExtension"/>
+        public bool Autolinks { get; init; }
+
+        /// <summary>
+        /// Allows the <see cref="OsuMarkdownContainer"/> to parse custom containers (used for flags and infoboxes).
+        /// </summary>
+        /// <seealso cref="CustomContainerExtension"/>
+        public bool CustomContainers { get; init; }
+
+        /// <summary>
+        /// Allows the <see cref="OsuMarkdownContainer"/> to parse custom attributes in block elements (used e.g. for custom anchor names in the wiki).
+        /// </summary>
+        /// <seealso cref="BlockAttributeExtension"/>
+        public bool BlockAttributes { get; init; }
+
+        /// <summary>
+        /// Returns a prepared <see cref="MarkdownPipeline"/> according to the options specified by the current <see cref="OsuMarkdownContainerOptions"/> instance.
+        /// </summary>
+        /// <remarks>
+        /// Compare: https://github.com/ppy/osu-web/blob/05488a96b25b5a09f2d97c54c06dd2bae59d1dc8/app/Libraries/Markdown/OsuMarkdown.php#L301
+        /// </remarks>
+        public MarkdownPipeline BuildPipeline()
+        {
+            var pipeline = new MarkdownPipelineBuilder()
+                           .UseAutoIdentifiers()
+                           .UsePipeTables()
+                           .UseEmphasisExtras(EmphasisExtraOptions.Strikethrough)
+                           .UseYamlFrontMatter();
+
+            if (Footnotes)
+                pipeline = pipeline.UseFootnotes();
+
+            if (Autolinks)
+                pipeline = pipeline.UseAutoLinks();
+
+            if (CustomContainers)
+                pipeline = pipeline.UseCustomContainers();
+
+            if (BlockAttributes)
+                pipeline = pipeline.UseBlockAttributes();
+
+            return pipeline.Build();
+        }
+    }
+}

osu.Game/Overlays/Comments/CommentMarkdownContainer.cs

@@ -11,7 +11,10 @@ namespace osu.Game.Overlays.Comments
 {
     public partial class CommentMarkdownContainer : OsuMarkdownContainer
     {
-        protected override bool Autolinks => true;
+        protected override OsuMarkdownContainerOptions Options => new OsuMarkdownContainerOptions
+        {
+            Autolinks = true
+        };
 
         protected override MarkdownHeading CreateHeading(HeadingBlock headingBlock) => new CommentMarkdownHeading(headingBlock);
 

osu.Game/Overlays/Wiki/Markdown/WikiMarkdownContainer.cs

@@ -16,8 +16,12 @@ namespace osu.Game.Overlays.Wiki.Markdown
 {
     public partial class WikiMarkdownContainer : OsuMarkdownContainer
     {
-        protected override bool Footnotes => true;
-        protected override bool CustomContainers => true;
+        protected override OsuMarkdownContainerOptions Options => new OsuMarkdownContainerOptions
+        {
+            Footnotes = true,
+            CustomContainers = true,
+            BlockAttributes = true
+        };
 
         public string CurrentPath
         {