From 1b7ce7c0ea4dca6a0a5590b82216841e02a32052 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Julius=20M=C3=BCller?= Date: Sat, 9 Jan 2021 16:37:49 +0100 Subject: [PATCH 1/3] ability to define toc position in mkdocs.yml --- mkdocs_with_pdf/generator.py | 5 ++++- mkdocs_with_pdf/toc.py | 14 +++++++++++--- 2 files changed, 15 insertions(+), 4 deletions(-) diff --git a/mkdocs_with_pdf/generator.py b/mkdocs_with_pdf/generator.py index 237277d5..21bbbd5e 100644 --- a/mkdocs_with_pdf/generator.py +++ b/mkdocs_with_pdf/generator.py @@ -102,7 +102,10 @@ def add_stylesheet(stylesheet: str): add_stylesheet(self._theme.get_stylesheet(self._options.debug_html)) for page in self._nav: - content = self._get_content(soup, page) + if getattr(page, "url", None) == "toc": + content = soup.new_tag('article', id='doc-toc') + else: + content = self._get_content(soup, page) if content: soup.body.append(content) diff --git a/mkdocs_with_pdf/toc.py b/mkdocs_with_pdf/toc.py index 5ac863b2..fe6a0e17 100644 --- a/mkdocs_with_pdf/toc.py +++ b/mkdocs_with_pdf/toc.py @@ -40,7 +40,11 @@ def makeLink(h: Tag) -> Tag: options.logger.debug(f"| [{h.get_text(separator=' ')}]({ref})") return li - toc = soup.new_tag('article', id='doc-toc') + toc = soup.find(id='doc-toc') + custom_doc_pos = True + if not toc: + toc = soup.new_tag('article', id='doc-toc') + custom_doc_pos = False title = soup.new_tag('h1') title.append(soup.new_string(options.toc_title)) toc.append(title) @@ -51,6 +55,9 @@ def makeLink(h: Tag) -> Tag: headings = soup.find_all(['h1', 'h2', 'h3']) for h in headings: + if h.find(string=options.toc_title): + continue + if h.name == 'h1': h1li = makeLink(h) @@ -84,8 +91,9 @@ def makeLink(h: Tag) -> Tag: else: continue pass - - soup.body.insert(0, toc) + + if not custom_doc_pos: + soup.body.insert(0, toc) def _inject_heading_order(soup: Tag, options: Options): From a4a90b81188b058341cd25d7d512cadb9726bb03 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Julius=20M=C3=BCller?= Date: Sat, 9 Jan 2021 17:39:38 +0100 Subject: [PATCH 2/3] make toc optional --- mkdocs_with_pdf/generator.py | 2 +- mkdocs_with_pdf/options.py | 2 ++ mkdocs_with_pdf/toc.py | 5 +++++ 3 files changed, 8 insertions(+), 1 deletion(-) diff --git a/mkdocs_with_pdf/generator.py b/mkdocs_with_pdf/generator.py index 21bbbd5e..f30b5556 100644 --- a/mkdocs_with_pdf/generator.py +++ b/mkdocs_with_pdf/generator.py @@ -102,7 +102,7 @@ def add_stylesheet(stylesheet: str): add_stylesheet(self._theme.get_stylesheet(self._options.debug_html)) for page in self._nav: - if getattr(page, "url", None) == "toc": + if getattr(page, "url", None) == "toc" and self._options.toc: content = soup.new_tag('article', id='doc-toc') else: content = self._get_content(soup, page) diff --git a/mkdocs_with_pdf/options.py b/mkdocs_with_pdf/options.py index 1e96f627..0ab6ca45 100644 --- a/mkdocs_with_pdf/options.py +++ b/mkdocs_with_pdf/options.py @@ -29,6 +29,7 @@ class Options(object): ('custom_template_path', config_options.Type(str, default="templates")), + ('toc', config_options.Type(bool, default=True)), ('toc_title', config_options.Type(str, default="Table of contents")), ('heading_shift', config_options.Type(bool, default=True)), ('toc_level', config_options.Type(int, default=2)), @@ -75,6 +76,7 @@ def __init__(self, local_config, config, logger: logging): self.custom_template_path = local_config['custom_template_path'] # TOC and Chapter heading + self.toc = local_config['toc'] self.toc_title = local_config['toc_title'] self.heading_shift = local_config['heading_shift'] self.toc_level = local_config['toc_level'] diff --git a/mkdocs_with_pdf/toc.py b/mkdocs_with_pdf/toc.py index fe6a0e17..25864332 100644 --- a/mkdocs_with_pdf/toc.py +++ b/mkdocs_with_pdf/toc.py @@ -12,6 +12,11 @@ def make_indexes(soup: PageElement, options: Options) -> None: options {Options} -- The options of this sequence. """ + if options.toc: + _make_indexes(soup, options) + + +def _make_indexes(soup: PageElement, options: Options) -> None: # Step 1: (re)ordered headdings _inject_heading_order(soup, options) From 8f13d21cc4742547e0bb98e72ebdbcf27c10379f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Julius=20M=C3=BCller?= Date: Mon, 18 Jan 2021 11:10:30 +0100 Subject: [PATCH 3/3] update README.md --- README.md | 28 ++++++++++++++++++++++++++-- 1 file changed, 26 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 3ede32e0..7be79a38 100644 --- a/README.md +++ b/README.md @@ -166,10 +166,16 @@ plugins: ##### for Heading and TOC +* `toc` + + Generate a Table of Contents. + **default**: `true` + _**since**: _ + * `toc_title` - Set the title text of _Table of Content_. - **default**: `Table of Content` + Set the title text of _Table of Contents_. + **default**: `Table of Contents` _**since**: `v0.4.0`_ * `heading_shift` @@ -194,6 +200,24 @@ plugins: Set the page `id` of `nav` url. If the `id` matches in this list, it will be excluded from the heading number addition and table of contents. **default**: `[]` +* Changing the position of the TOC + + By default, the TOC is inserted at the beginning of the document. + You can change the position of the TOC by adding a `- toc` entry to the nav section. + + ``` + nav: + - Foreword: foreword.md + - toc + - Introduction: introduction.md + ... + ``` + + Note: The TOC must be toplevel. + It can not be inserted in a nested docment section. + + _**since**: _ + ##### for Page * `exclude_pages`