Allow use category id as heading's id (#66)

Add config `category_heading`.

Resolves #65

README.md

@@ -516,6 +516,11 @@ The configuration example above changes the default configuration to show all pr
         <td>If <code>True</code>, generate a table of content with all categories.</td>
         <td><code>True</code></td>
     </tr>
+    <tr>
+        <td><code>category_heading</code></td>
+        <td>How categories headings are generated. If <code>simple</code>, headings will be <code>## Category</code>, and IDs are set by GitHub. If <code>robust</code>, headings will be <code>&lt;h2 id='category-id'&gt;Category&lt;/h2&gt;</code>. (TOC relies on these IDs.) If all of your categories' names are ASCII, use <code>simple</code>.</td>
+        <td><code>simple</code><td>
+    </tr>
     <tr>
         <td><code>generate_legend</code></td>
         <td>If <code>True</code>, generate a legend containing explanations for the used emojis.</td>

src/best_of/default_config.py

@@ -46,6 +46,9 @@ def prepare_configuration(cfg: dict) -> Dict:
     if "generate_toc" not in config:
         config.generate_toc = True
 
+    if "category_heading" not in config:
+        config.category_heading = "simple"
+
     if "generate_legend" not in config:
         config.generate_legend = True
 

src/best_of/generators/markdown_list.py

@@ -332,7 +332,7 @@ def generate_project_md(
 
 
 def generate_category_md(
-    category: Dict, config: Dict, labels: list, title_md_prefix: str = "##"
+    category: Dict, config: Dict, labels: list, heading_level: int = 2
 ) -> str:
     if category.ignore:
         return ""
@@ -349,7 +349,21 @@ def generate_category_md(
         return ""
 
     category_md: str = ""
-    category_md += title_md_prefix + " " + category.title + "\n\n"
+
+    if config.category_heading == "simple":
+        category_md += "#" * heading_level + " " + category.title + "\n\n"
+    elif config.category_heading == "robust":
+        category_md += (
+            f"<h{heading_level} id='{category.category}'>{category.title}"
+            f"</h{heading_level}>\n\n"
+        )
+    else:
+        raise Exception(
+            "Configuration category_heading is not valid: "
+            f"“{config.category_heading}”. "
+            "Valid values are “simple”, “robust”."
+        )
+
     back_to_top_anchor = "#contents"
     if not config.generate_toc:
         # Use # anchor to get back to top of repo
@@ -434,10 +448,8 @@ def generate_changes_md(projects: list, config: Dict, labels: list) -> str:
     return markdown
 
 
-def generate_legend(
-    configuration: Dict, labels: list, title_md_prefix: str = "##"
-) -> str:
-    legend_md = title_md_prefix + " Explanation\n"
+def generate_legend(configuration: Dict, labels: list, heading_level: int = 2) -> str:
+    legend_md = "#" * heading_level + " Explanation\n"
     # Score that various project-quality metrics
     # score for a package based on a number of metrics
     legend_md += "- 🥇🥈🥉&nbsp; Combined project-quality score\n"
@@ -495,7 +507,16 @@ def generate_toc(categories: OrderedDict, config: Dict) -> str:
         if category_info.ignore:
             continue
 
-        url = "#" + process_md_link(category_info.title)
+        if config.category_heading == "simple":
+            url = "#" + process_md_link(category_info.title)
+        elif config.category_heading == "robust":
+            url = "#" + category_info.category
+        else:
+            raise Exception(
+                "Configuration category_heading is not valid: "
+                f"“{config.category_heading}”. "
+                "Valid values are “simple”, “robust”."
+            )
 
         project_count = 0
         if category_info.projects: