def _rearrange_section(self, section: Section) -> Section:
section.children = self._rearrange_list_of_navigation_items(
section.children, )
index_page = find_index_page_in_section(section)
if index_page is None:
section.position = PAGE_DEFAULT_POSITION
else:
section.position = index_page.position
if index_page.title:
section.title = index_page.title
return section
def _set_title(section: Section, meta: Meta):
if meta.title is not None:
section.title = meta.title
def on_nav(self, nav, config, files):
"""
From MkDocs documentation:
==========================
The nav event is called after the site navigation is created and can
be used to alter the site navigation.
Args:
nav: Our navbar
config: Global configuration
files: List of files
Returns:
A modified navbar
"""
# Our plugin code starts here!
# We are starting by reading the configuration parameters
# for our plugin
# How many articles do we have to display in the blog part.
# This number will be doubled by the nested "previous articles"
# section
articles = self.config["articles"]
# The title of the section that will contain the blog part
# By default, it searches for a section titled "blog"
blog_section = self.config["folder"]
# Searches for a section that is titled the blog section
blogs_found = [(i, e) for i, e in enumerate(nav.items)
if e.title and e.title.lower() == blog_section.lower()]
# Have we founded that?
if not blogs_found:
# Nope. We'll give back control to MkDocs...
return nav
# Yes, since we are still here we did found at least one blog folder.
# We'll just need to pick up the first occurrence found
blog_position, blog = blogs_found[0]
# Now it's time to empty whatever that section was containing
blog.children = []
# If the number of articles that we are going to display will be
# too high, we'll also need a section in which we could place the
# exceeding articles
more = Section(title="", children=[])
# All right, it's time to start searching our mkdocs repository for
# potentials blog articles. We want to sort our list of pages by
# their URL value, in descending order.
# Why? Because each of our blog articles will be saved in this
# format:
#
# mkdocs/docs/blog/2020/01/2020-01-20--first_post.md
# mkdocs/docs/blog/2020/01/2020-01-25--second_post.md
# mkdocs/docs/blog/2020/02/2020-02-01--third_post.md
#
# By reversing the alphabetical order, We'll ensure to get this
# articles list in this order:
#
# "third post" (2020-02-01--third_post.md)
# "second post" (2020-01-25--second_post.md)
# "first post" (2020-01-20--first_post.md)
#
for page in sorted(nav.pages,
key=lambda x: x.url, reverse=True):
# Let's have a look at the URL of this page... hmm...
# Is it nested in the folder/section we have chosen for keeping
# our blog articles ? Let's have a case-insensitive check...
if blog_section + "/" in page.url.lower():
# Yes, it is in the right folder / section.
# Now, let's check if we already have enough articles in
# our blog section
if len(blog.children) < articles:
# No, there's still space available.
# Let's add this page to our blog section
blog.children.append(page)
else:
# Our blog section is already at full capacity.
# Well, let's see if we can add this article to the
# "previous articles" section that (maybe) will be
# added at the end
# Is the "More articles" section empty ?
if len(more.children) == 0:
subsection = Section(title="", children=[])
more.children.append(subsection)
else:
# Or the default subsection is already full ?
# noinspection PyUnboundLocalVariable
if len(subsection.children) >= articles:
# Yes. Add a new subsection inside of it
subsection = Section(title="", children=[])
more.children.append(subsection)
subsection.children.append(page)
# All right, we just finished scanning our MkDocs repository for
# articles. Let's add some minor finishing touches to our sections.
# Did the user allows to show this section?
if self.config["display-more-articles"]:
# How many articles do we have stored in the "More articles"
# section?
articles_count = sum([len(sub.children)
for sub in more.children])
if articles_count > 0:
# We will change the title of each subsection to display
# something like "Page 1 of X"
last_page = len(more.children)
for actual_page, subpage in enumerate(more.children,
start=1):
subpage.title = self.config["pagination"]\
.replace("%", str(actual_page), 1)\
.replace("%", str(last_page), 1)
# Last thing before adding this section to our blog...
# We need to change our "More article" section title
# accordingly to what our user has chosen
more.title = self.config["more-articles"]\
.replace("%", str(articles_count))
# Finished. Let's add our "More articles" section to our
# Blog section.
blog.children.append(more)
# THE FOLLOWING 3 LINES OF CODE ARE JUST MEANT FOR DEBUGGING PURPOSES
# ===================================================================
# import pydevd_pycharm
# pydevd_pycharm.settrace('localhost', port=5000, stdoutToServer=True,
# stderrToServer=True)
# Search for the blog section in the nav, and move it to the bottom
# Let's start by removing the blog section from wherever MkDocs has
# put it, in first place
del(nav.items[blog_position])
# Now we'll append the blog section at the end of the nav element
nav.items.append(blog)
# All finished. We can give back our modified nav to MkDocs and enjoy
# our new blog section!
return nav
