Support Markdown heading aliases

CHANGES.md

@@ -17,6 +17,8 @@ This file describes changes in the AutoDoc package.
     AutoDoc marker at the start of a line (ignoring leading whitespace)
   - Warn if a chunk is defined (via `@BeginChunk`/`@BeginCode`) but never
     inserted (via `@InsertChunk`/`@InsertCode`)
+  - Allow using Markdown-style headings `#`/`##`/`###` as aliases for
+    `@Chapter`/`@Section`/`@Subsection` in `.autodoc` files and doc comments
 
 2025.12.19
   - Don't replace empty lines in `@BeginCode` blocks by `<P/>`

gap/Parser.gi

@@ -19,10 +19,50 @@ BindGlobal( "AUTODOC_PositionPrefixShebang",
     return fail;
 end );
 
+##
+BindGlobal( "AUTODOC_SplitMarkdownHeading",
+  function( line )
+    local trimmed, level, first_non_hash;
+    trimmed := StripBeginEnd( line, " \t\r\n" );
+    if trimmed = "" or trimmed[ 1 ] <> '#' then
+        return fail;
+    fi;
+
+    level := 1;
+    while level < Length( trimmed ) and trimmed[ level + 1 ] = '#' do
+        level := level + 1;
+    od;
+    if level > 3 then
+        return fail;
+    fi;
+
+    first_non_hash := level + 1;
+    if first_non_hash <= Length( trimmed ) and
+       not ( trimmed[ first_non_hash ] in " \t\r\n" ) then
+        return fail;
+    fi;
+
+    while first_non_hash <= Length( trimmed ) and
+          trimmed[ first_non_hash ] in " \t\r\n" do
+        first_non_hash := first_non_hash + 1;
+    od;
+
+    if level = 1 then
+        return [ "@Chapter", trimmed{ [ first_non_hash .. Length( trimmed ) ] } ];
+    elif level = 2 then
+        return [ "@Section", trimmed{ [ first_non_hash .. Length( trimmed ) ] } ];
+    fi;
+    return [ "@Subsection", trimmed{ [ first_non_hash .. Length( trimmed ) ] } ];
+end );
+
 ##
 BindGlobal( "AUTODOC_SplitCommandAndArgument",
   function( line )
-    local command_start, argument_start, command, argument;
+    local command_start, argument_start, command, argument, heading;
+    heading := AUTODOC_SplitMarkdownHeading( line );
+    if heading <> fail then
+        return heading;
+    fi;
     command_start := PositionSublist( line, "@" );
     if command_start = fail then
         return [ "STRING", line ];

tst/misc.tst

@@ -95,6 +95,14 @@ gap> Scan_for_AutoDoc_Part( "   @NoArg", true );
 [ "@NoArg", "" ]
 gap> Scan_for_AutoDoc_Part( "no command here", true );
 [ "STRING", "no command here" ]
+gap> Scan_for_AutoDoc_Part( "# Heading chapter", true );
+[ "@Chapter", "Heading chapter" ]
+gap> Scan_for_AutoDoc_Part( "## Heading section", true );
+[ "@Section", "Heading section" ]
+gap> Scan_for_AutoDoc_Part( "### Heading subsection", true );
+[ "@Subsection", "Heading subsection" ]
+gap> Scan_for_AutoDoc_Part( "  #! ## Comment section", false );
+[ "@Section", "Comment section" ]
 
 #
 # AutoDoc_Parser_ReadFiles: multiline InstallMethod parsing

tst/worksheets/autoplain.expected/_Chapter_Test.xml

@@ -6,6 +6,12 @@
 
 Does AutoDoc have a way to allow that header block not to appear in
 the documentation generated from a <F>.autodoc</F> file like this?
+<Section Label="Chapter_Test_Section_First_Section">
+<Heading>First Section</Heading>
+
+<Subsection Label="Chapter_Test_Section_First_Section_Subsection_First_Subsection">
+<Heading>First Subsection</Heading>
+
 <Example><![CDATA[
 gap> S5 := SymmetricGroup(5);
 Sym( [ 1 .. 5 ] )
@@ -24,5 +30,11 @@ gap> Size(A5);
 
 
 And we wrap up with some dummy text
+</Subsection>
+
+
+</Section>
+
+
 </Chapter>
 

tst/worksheets/autoplain.expected/tst/plain_file.autodoc_test01.tst

@@ -10,13 +10,13 @@
 #
 gap> START_TEST("plain_file.autodoc_test01.tst");
 
-# _Chapter_Test.xml:9-14
+# _Chapter_Test.xml:15-20
 gap> S5 := SymmetricGroup(5);
 Sym( [ 1 .. 5 ] )
 gap> Size(S5);
 120
 
-# _Chapter_Test.xml:18-23
+# _Chapter_Test.xml:24-29
 gap> A5 := AlternatingGroup(5);
 Alt( [ 1 .. 5 ] )
 gap> Size(A5);

tst/worksheets/autoplain.sheet/plain.autodoc

@@ -1,9 +1,11 @@
 @Title Plain file.autodoc Test
 @Date 2018-08-30
 
-@Chapter Test
+# Test
 Does AutoDoc have a way to allow that header block not to appear in
 the documentation generated from a <F>.autodoc</F> file like this?
+## First Section
+### First Subsection
 @BeginExampleSession
 gap> S5 := SymmetricGroup(5);
 Sym( [ 1 .. 5 ] )