diff --git a/sphinx/_templates/local_md_files.html b/sphinx/_templates/structure.html
similarity index 100%
rename from sphinx/_templates/local_md_files.html
rename to sphinx/_templates/structure.html
diff --git a/sphinx/conf.py b/sphinx/conf.py
index 2b1e8555..dbb4a909 100644
--- a/sphinx/conf.py
+++ b/sphinx/conf.py
@@ -33,7 +33,7 @@ html_sidebars = {
#'globaltoc.html',
# 'relations.html',
# 'sourcelink.html',
- 'local_md_files.html', # Include your custom template
+ 'structure.html', # Include your custom template
# 'searchbox.html',
]
}
diff --git a/sphinx/extensions/nav_utils.py b/sphinx/extensions/nav_utils.py
index 1a604d07..c2187eca 100644
--- a/sphinx/extensions/nav_utils.py
+++ b/sphinx/extensions/nav_utils.py
@@ -17,8 +17,11 @@ def extract_headings_from_file(filepath, max_level=MAX_HEADING_LEVEL):
Extract headings from a file.
For Markdown (.md) files, looks for lines starting with '#' (up to max_level).
For reStructuredText (.rst) files, looks for a line immediately followed by an underline.
+ If no headings are found and the file is an index file while a README.md exists in the same folder,
+ it will try to extract headings from the README.md instead.
Returns a list of dictionaries with keys: 'level', 'text', and 'anchor' (if applicable).
"""
+ import os, re
headings = []
ext = os.path.splitext(filepath)[1].lower()
try:
@@ -41,16 +44,28 @@ def extract_headings_from_file(filepath, max_level=MAX_HEADING_LEVEL):
headings.append({'level': level, 'text': heading_text, 'anchor': anchor})
elif ext == '.rst':
lines = f.readlines()
- for i in range(len(lines)-1):
+ for i in range(len(lines) - 1):
text_line = lines[i].rstrip("\n")
underline = lines[i+1].rstrip("\n")
if len(underline) >= 3 and re.fullmatch(r'[-=~\^\+"\'`]+', underline):
level = 1
heading_text = text_line.strip()
- # For reST, the anchor is left empty (can be generated later if needed)
headings.append({'level': level, 'text': heading_text, 'anchor': ''})
except Exception as e:
print(f"Warning: Error reading {filepath}: {e}")
+
+ # If no headings were found and the file is an index file,
+ # then try to load headings from a README.md in the same folder.
+ if not headings:
+ base = os.path.basename(filepath).lower()
+ if base == 'index.rst':
+ folder = os.path.dirname(filepath)
+ readme_path = os.path.join(folder, 'README.md')
+ if os.path.isfile(readme_path):
+ try:
+ headings = extract_headings_from_file(readme_path, max_level)
+ except Exception as e:
+ print(f"Warning: Error reading fallback README.md in {folder}: {e}")
return headings
def group_headings(headings):