def build_autodoc(page, config, site_navigation, env, dump_json, dirty=False):
"""
Build autodoc, just like mkdocs.commands.build._build_page
"""
input_path, output_path = get_complete_paths(config, page)
try:
input_content = io.open(input_path, 'r', encoding='utf-8').read()
except IOError:
log.error('file not found: %s', input_path)
raise
# render autodoc contents
tmplstr = io.open(TEMPLATE_PATH).read()
template = env.from_string(tmplstr)
contents, titles = parse_selected(input_content)
table_of_contents = create_toc(titles)
html_content = template.render(contents=contents)
# render page
meta = None
context = get_global_context(site_navigation, config)
context.update(get_page_context(
page, html_content, table_of_contents, meta, config
))
template = env.get_template('base.html')
output_content = template.render(context)
utils.write_file(output_content.encode('utf-8'), output_path)
return html_content, table_of_contents, None
def _build_extra_template(template_name, files, config, nav):
""" Build user templates which are not part of the theme. """
log.debug("Building extra template: {}".format(template_name))
file = files.get_file_from_path(template_name)
if file is None:
log.warning("Template skipped: '{}' not found in docs_dir.".format(
template_name))
return
try:
with open(file.abs_src_path, 'r', encoding='utf-8',
errors='strict') as f:
template = jinja2.Template(f.read())
except Exception as e:
log.warning("Error reading template '{}': {}".format(template_name, e))
return
output = _build_template(template_name, template, files, config, nav)
if output.strip():
utils.write_file(output.encode('utf-8'), file.abs_dest_path)
else:
log.info("Template skipped: '{}' generated empty output.".format(
template_name))
def build_pages(config, dump_json=False):
"""
Builds all the pages and writes them into the build directory.
"""
site_navigation = nav.SiteNavigation(config['pages'], config['use_directory_urls'])
loader = jinja2.FileSystemLoader(config['theme_dir'] + [config['mkdocs_templates'], ])
env = jinja2.Environment(loader=loader)
search_index = search.SearchIndex()
build_template('404.html', env, config, site_navigation)
if not build_template('search.html', env, config, site_navigation):
log.debug("Search is enabled but the theme doesn't contain a "
"search.html file. Assuming the theme implements search "
"within a modal.")
build_sitemap(config, env, site_navigation)
build_extra_templates(config['extra_templates'], config, site_navigation)
for page in site_navigation.walk_pages():
try:
log.debug("Building page %s", page.input_path)
build_result = _build_page(page, config, site_navigation, env,
dump_json)
html_content, table_of_contents, _ = build_result
search_index.add_entry_from_context(
page, html_content, table_of_contents)
except Exception:
log.error("Error building page %s", page.input_path)
raise
search_index = search_index.generate_search_index()
json_output_path = os.path.join(config['site_dir'], 'mkdocs', 'search_index.json')
utils.write_file(search_index.encode('utf-8'), json_output_path)
def build_pages(config, dump_json=False):
"""
Builds all the pages and writes them into the build directory.
"""
site_navigation = nav.SiteNavigation(config['pages'], config['use_directory_urls'])
loader = jinja2.FileSystemLoader(config['theme_dir'])
env = jinja2.Environment(loader=loader)
search_index = search.SearchIndex()
build_template('404.html', env, config, site_navigation)
if not build_template('search.html', env, config, site_navigation):
log.debug("Search is enabled but the theme doesn't contain a "
"search.html file. Assuming the theme implements search "
"within a modal.")
for page in site_navigation.walk_pages():
try:
log.debug("Building page %s", page.input_path)
html_content, table_of_contents, meta = _build_page(
page, config, site_navigation, env, dump_json)
search_index.add_entry_from_context(
page, html_content, table_of_contents)
except:
log.error("Error building page %s", page.input_path)
raise
search_index = search_index.generate_search_index()
json_output_path = os.path.join(config['site_dir'], 'mkdocs', 'search_index.json')
utils.write_file(search_index.encode('utf-8'), json_output_path)
def build_pages(config):
"""
Builds all the pages and writes them into the build directory.
"""
site_navigation = nav.SiteNavigation(config['pages'], config['url_format'])
loader = jinja2.FileSystemLoader(config['theme_dir'])
env = jinja2.Environment(loader=loader)
for page in site_navigation.walk_pages():
# Read the input file
input_path = os.path.join(config['docs_dir'], page.input_path)
input_content = open(input_path, 'r').read().decode('utf-8')
# Process the markdown text
html_content, table_of_contents, meta = convert_markdown(input_content)
html_content = post_process_html(html_content, site_navigation, config['url_format'])
context = get_context(
page, html_content, site_navigation,
table_of_contents, meta, config
)
# Allow 'template:' override in md source files.
if 'template' in meta:
template = env.get_template(meta['template'][0])
else:
template = env.get_template('base.html')
# Render the template.
output_content = template.render(context)
# Write the output file.
output_path = os.path.join(config['site_dir'], page.output_path)
utils.write_file(output_content.encode('utf-8'), output_path)
def on_post_build(self, config: Config, **kwargs) -> None: # noqa: W0613,R0201 (unused arguments, cannot be static)
"""Teardown the handlers.
Hook for the [`on_post_build` event](https://www.mkdocs.org/user-guide/plugins/#on_post_build).
This hook is used to teardown all the handlers that were instantiated and cached during documentation buildup.
For example, the [Python handler's collector][mkdocstrings.handlers.python.PythonCollector] opens a subprocess
in the background and keeps it open to feed it the "autodoc" instructions and get back JSON data. Therefore,
it must close it at some point, and it does it in its
[`teardown()` method][mkdocstrings.handlers.python.PythonCollector.teardown] which is indirectly called by
this hook.
Arguments:
config: The MkDocs config object.
kwargs: Additional arguments passed by MkDocs.
"""
if self.handlers:
css_content = "\n".join(handler.renderer.extra_css for handler in self.handlers.seen_handlers)
write_file(css_content.encode("utf-8"), os.path.join(config["site_dir"], self.css_filename))
if self.inventory_enabled:
log.debug("Creating inventory file objects.inv")
inv_contents = self.handlers.inventory.format_sphinx()
write_file(inv_contents, os.path.join(config["site_dir"], "objects.inv"))
log.debug("Tearing handlers down")
self.handlers.teardown()
def on_post_build(self, config, **kwargs):
"Build search index."
output_base_path = os.path.join(config['site_dir'], 'search')
search_index = self.search_index.generate_search_index()
json_output_path = os.path.join(output_base_path, 'search_index.json')
utils.write_file(search_index.encode('utf-8'), json_output_path)
if not ('search_index_only' in config['theme']
and config['theme']['search_index_only']):
# Include language support files in output. Copy them directly
# so that only the needed files are included.
files = []
if len(self.config['lang']) > 1 or 'en' not in self.config['lang']:
files.append('lunr.stemmer.support.js')
if len(self.config['lang']) > 1:
files.append('lunr.multi.js')
if ('ja' in self.config['lang'] or 'jp' in self.config['lang']):
files.append('tinyseg.js')
for lang in self.config['lang']:
if (lang != 'en'):
files.append('lunr.{}.js'.format(lang))
for filename in files:
from_path = os.path.join(base_path, 'lunr-language', filename)
to_path = os.path.join(output_base_path, filename)
utils.copy_file(from_path, to_path)
def on_env(self, env, config: Config, **kwargs):
"""Extra actions that need to happen after all Markdown rendering and before HTML rendering.
- Write mkdocstrings' extra files into the site dir.
- Gather results from background inventory download tasks.
"""
if self._handlers:
css_content = "\n".join(handler.renderer.extra_css
for handler in self.handlers.seen_handlers)
write_file(css_content.encode("utf-8"),
os.path.join(config["site_dir"], self.css_filename))
if self.inventory_enabled:
log.debug("Creating inventory file objects.inv")
inv_contents = self.handlers.inventory.format_sphinx()
write_file(inv_contents,
os.path.join(config["site_dir"], "objects.inv"))
if self._inv_futures:
log.debug(
f"Waiting for {len(self._inv_futures)} inventory download(s)")
concurrent.futures.wait(self._inv_futures, timeout=30)
for k, v in collections.ChainMap(
*(f.result() for f in self._inv_futures)).items():
config["plugins"]["autorefs"].register_url(k, v)
self._inv_futures = []
def build_pages(config):
"""
Builds all the pages and writes them into the build directory.
"""
site_navigation = nav.SiteNavigation(config['pages'])
loader = jinja2.FileSystemLoader(config['theme_dir'])
env = jinja2.Environment(loader=loader)
for page in site_navigation.walk_pages():
# Read the input file
input_path = os.path.join(config['docs_dir'], page.input_path)
input_content = open(input_path, 'r').read().decode('utf-8')
# Process the markdown text
html_content, table_of_contents, meta = convert_markdown(input_content)
html_content = post_process_html(html_content, site_navigation)
context = get_context(page, html_content, site_navigation,
table_of_contents, meta, config)
# Allow 'template:' override in md source files.
if 'template' in meta:
template = env.get_template(meta['template'][0])
else:
template = env.get_template('base.html')
# Render the template.
output_content = template.render(context)
# Write the output file.
output_path = os.path.join(config['site_dir'], page.output_path)
utils.write_file(output_content.encode('utf-8'), output_path)
def _build_theme_template(template_name, env, files, config, nav):
""" Build a template using the theme environment. """
log.debug("Building theme template: {}".format(template_name))
try:
template = env.get_template(template_name)
except TemplateNotFound:
log.warning(
"Template skipped: '{}' not found in theme directories.".format(
template_name))
return
output = _build_template(template_name, template, files, config, nav)
if output.strip():
output_path = os.path.join(config['site_dir'], template_name)
utils.write_file(output.encode('utf-8'), output_path)
if template_name == 'sitemap.xml':
log.debug("Gzipping template: %s", template_name)
gz_filename = '{}.gz'.format(output_path)
with open(gz_filename, 'wb') as f:
timestamp = utils.get_build_timestamp()
with gzip.GzipFile(fileobj=f,
filename=gz_filename,
mode='wb',
mtime=timestamp) as gz_buf:
gz_buf.write(output.encode('utf-8'))
else:
log.info("Template skipped: '{}' generated empty output.".format(
template_name))
def _build_page(page, config, site_navigation, env, dirty=False):
""" Build a Markdown page and pass to theme template. """
# Run the `pre_page` plugin event
page = config['plugins'].run_event('pre_page',
page,
config=config,
site_navigation=site_navigation)
page.read_source(config=config)
# Run `page_markdown` plugin events.
page.markdown = config['plugins'].run_event(
'page_markdown',
page.markdown,
page=page,
config=config,
site_navigation=site_navigation)
page.render(config, site_navigation)
# Run `page_content` plugin events.
page.content = config['plugins'].run_event('page_content',
page.content,
page=page,
config=config,
site_navigation=site_navigation)
context = get_context(site_navigation, config, page)
# Allow 'template:' override in md source files.
if 'template' in page.meta:
template = env.get_template(page.meta['template'])
else:
template = env.get_template('main.html')
# Run `page_context` plugin events.
context = config['plugins'].run_event('page_context',
context,
page=page,
config=config,
site_navigation=site_navigation)
# Render the template.
output_content = template.render(context)
# Run `post_page` plugin events.
output_content = config['plugins'].run_event('post_page',
output_content,
page=page,
config=config)
# Write the output file.
if output_content.strip():
utils.write_file(output_content.encode('utf-8'), page.abs_output_path)
else:
log.info("Page skipped: '{}'. Generated empty output.".format(
page.title))
def _build_page(page, config, doc_files, nav, env, dirty=False):
""" Pass a Page to theme template and write output to site_dir. """
try:
# When --dirty is used, only build the page if the file has been modified since the
# previous build of the output.
if dirty and not page.file.is_modified():
return
log.debug(f"Building page {page.file.src_path}")
# Activate page. Signals to theme that this is the current page.
page.active = True
context = get_context(nav, doc_files, config, page)
# Allow 'template:' override in md source files.
if 'template' in page.meta:
template = env.get_template(page.meta['template'])
else:
template = env.get_template('main.html')
# Run `page_context` plugin events.
context = config['plugins'].run_event('page_context',
context,
page=page,
config=config,
nav=nav)
# Render the template.
output = template.render(context)
# Run `post_page` plugin events.
output = config['plugins'].run_event('post_page',
output,
page=page,
config=config)
# Write the output file.
if output.strip():
utils.write_file(
output.encode('utf-8', errors='xmlcharrefreplace'),
page.file.abs_dest_path)
else:
log.info(
f"Page skipped: '{page.file.src_path}'. Generated empty output."
)
# Deactivate page
page.active = False
except Exception as e:
message = f"Error building page '{page.file.src_path}':"
# Prevent duplicated the error message because it will be printed immediately afterwards.
if not isinstance(e, BuildError):
message += f" {e}"
log.error(message)
raise
def build_sitemap(config, env, site_navigation):
log.debug("Building sitemap.xml")
template = env.get_template('sitemap.xml')
context = get_global_context(site_navigation, config)
output_content = template.render(context)
output_path = os.path.join(config['site_dir'], 'sitemap.xml')
utils.write_file(output_content.encode('utf-8'), output_path)
def build_sitemap(config, env, site_navigation):
log.debug("Building sitemap.xml")
template = env.get_template('sitemap.xml')
context = get_global_context(site_navigation, config)
output_content = template.render(context)
output_path = os.path.join(config['site_dir'], 'sitemap.xml')
utils.write_file(output_content.encode('utf-8'), output_path)
def _build_page(page, config, site_navigation, env, dump_json):
# Read the input file
input_path = os.path.join(config['docs_dir'], page.input_path)
try:
input_content = io.open(input_path, 'r', encoding='utf-8').read()
except IOError:
log.error('file not found: %s', input_path)
raise
# Process the markdown text
html_content, table_of_contents, meta = convert_markdown(
markdown_source=input_content,
config=config,
site_navigation=site_navigation
)
context = get_global_context(site_navigation, config)
context.update(get_page_context(
page, html_content, table_of_contents, meta, config
))
# Allow 'template:' override in md source files.
if 'template' in meta:
template = env.get_template(meta['template'][0])
else:
try:
template = env.get_template('main.html')
except jinja2.TemplateNotFound:
# TODO: Remove this in version 1.0
template = env.get_template('base.html')
log.warn(
"Your theme does not appear to contain a 'main.html' template. "
"The 'base.html' template was used instead, which is deprecated. "
"Update your theme so that the primary entry point is 'main.html'."
)
# Render the template.
output_content = template.render(context)
# Write the output file.
output_path = os.path.join(config['site_dir'], page.output_path)
if dump_json:
json_context = {
'content': context['content'],
'title': context['current_page'].title,
'url': context['current_page'].abs_url,
'language': 'en',
}
json_output = json.dumps(json_context, indent=4).encode('utf-8')
utils.write_file(json_output, output_path.replace('.html', '.json'))
else:
utils.write_file(output_content.encode('utf-8'), output_path)
return html_content, table_of_contents, meta
def build_pages(config, dump_json=False):
"""
Builds all the pages and writes them into the build directory.
"""
site_navigation = nav.SiteNavigation(config['pages'],
config['use_directory_urls'])
loader = jinja2.FileSystemLoader(config['theme_dir'])
env = jinja2.Environment(loader=loader)
build_404(config, env, site_navigation)
for page in site_navigation.walk_pages():
# Read the input file
input_path = os.path.join(config['docs_dir'], page.input_path)
try:
input_content = open(input_path, 'r').read()
except IOError:
log.error('file not found: %s' % input_path)
if PY2:
input_content = input_content.decode('utf-8')
# Process the markdown text
html_content, table_of_contents, meta = convert_markdown(
input_content,
site_navigation,
extensions=config['markdown_extensions'],
strict=config['strict'])
context = get_global_context(site_navigation, config)
context.update(
get_page_context(page, html_content, site_navigation,
table_of_contents, meta, config))
# Allow 'template:' override in md source files.
if 'template' in meta:
template = env.get_template(meta['template'][0])
else:
template = env.get_template('base.html')
# Render the template.
output_content = template.render(context)
# Write the output file.
output_path = os.path.join(config['site_dir'], page.output_path)
if dump_json:
json_context = {
'content': context['content'],
'title': context['current_page'].title,
'url': context['current_page'].abs_url,
'language': 'en',
}
utils.write_file(
json.dumps(json_context, indent=4).encode('utf-8'),
output_path.replace('.html', '.json'))
else:
utils.write_file(output_content.encode('utf-8'), output_path)
def _build_page(page, config, site_navigation, env, dump_json, dirty=False):
# Get the input/output paths
input_path, output_path = get_complete_paths(config, page)
# Read the input file
try:
input_content = io.open(input_path, 'r', encoding='utf-8').read()
except IOError:
log.error('file not found: %s', input_path)
raise
# Process the markdown text
html_content, table_of_contents, meta = convert_markdown(
markdown_source=input_content,
config=config,
site_navigation=site_navigation
)
context = get_global_context(site_navigation, config)
context.update(get_page_context(
page, html_content, table_of_contents, meta, config
))
# Allow 'template:' override in md source files.
if 'template' in meta:
template = env.get_template(meta['template'][0])
else:
try:
template = env.get_template('main.html')
except jinja2.TemplateNotFound:
# TODO: Remove this in version 1.0
template = env.get_template('base.html')
log.warn(
"Your theme does not appear to contain a 'main.html' template. "
"The 'base.html' template was used instead, which is deprecated. "
"Update your theme so that the primary entry point is 'main.html'."
)
# Render the template.
output_content = template.render(context)
# Write the output file.
if dump_json:
json_context = {
'content': context['content'],
'title': context['current_page'].title,
'url': context['current_page'].abs_url,
'language': 'en',
}
json_output = json.dumps(json_context, indent=4).encode('utf-8')
utils.write_file(json_output, output_path.replace('.html', '.json'))
else:
utils.write_file(output_content.encode('utf-8'), output_path)
return html_content, table_of_contents, meta
def build_pages(config, dump_json=False):
"""
Builds all the pages and writes them into the build directory.
"""
site_navigation = nav.SiteNavigation(config['pages'], config['use_directory_urls'])
loader = jinja2.FileSystemLoader(config['theme_dir'])
env = jinja2.Environment(loader=loader)
build_404(config, env, site_navigation)
for page in site_navigation.walk_pages():
# Read the input file
input_path = os.path.join(config['docs_dir'], page.input_path)
try:
input_content = open(input_path, 'r').read()
except IOError:
log.error('file not found: %s' % input_path)
continue
if PY2:
input_content = input_content.decode('utf-8')
# Process the markdown text
html_content, table_of_contents, meta = convert_markdown(
input_content, site_navigation,
extensions=config['markdown_extensions'], strict=config['strict']
)
context = get_global_context(site_navigation, config)
context.update(get_page_context(
page, html_content, site_navigation,
table_of_contents, meta, config
))
# Allow 'template:' override in md source files.
if 'template' in meta:
template = env.get_template(meta['template'][0])
else:
template = env.get_template('base.html')
# Render the template.
output_content = template.render(context)
# Write the output file.
output_path = os.path.join(config['site_dir'], page.output_path)
if dump_json:
json_context = {
'content': context['content'],
'title': context['current_page'].title,
'url': context['current_page'].abs_url,
'language': 'en',
}
utils.write_file(json.dumps(json_context, indent=4).encode('utf-8'), output_path.replace('.html', '.json'))
else:
utils.write_file(output_content.encode('utf-8'), output_path)
def build_404(config, env, site_navigation):
try:
template = env.get_template("404.html")
except TemplateNotFound:
return
global_context = get_global_context(site_navigation, config)
output_content = template.render(global_context)
output_path = os.path.join(config["site_dir"], "404.html")
utils.write_file(output_content.encode("utf-8"), output_path)
def build_404(config, env, site_navigation):
try:
template = env.get_template('404.html')
except TemplateNotFound:
return
global_context = get_global_context(site_navigation, config)
output_content = template.render(global_context)
output_path = os.path.join(config['site_dir'], '404.html')
utils.write_file(output_content.encode('utf-8'), output_path)
def build_404(config, env, site_navigation):
log.debug("Building 404.html page")
try:
template = env.get_template('404.html')
except TemplateNotFound:
return
global_context = get_global_context(site_navigation, config)
output_content = template.render(global_context)
output_path = os.path.join(config['site_dir'], '404.html')
utils.write_file(output_content.encode('utf-8'), output_path)
def on_post_build(self, config, **kwargs):
if 'search' in config['plugins']:
output_base_path = os.path.join(config['site_dir'], 'search')
json_output_path = os.path.join(output_base_path, 'search_index.json')
js_output_path = os.path.join(output_base_path, 'search_index.js')
# Open JSON search index file
f = open(json_output_path,"r")
# Modify file to provide a Promise resolving with the contents of the search index
search_index = "const local_index = " + f.read() + "; var search = { index: new Promise(resolve => setTimeout(() => resolve(local_index), " + str(self.config['promise_delay']) + ")) }"
# Write to JSON file and rename JSON to JS
utils.write_file(search_index.encode('utf-8'), json_output_path)
f.close()
os.rename(json_output_path, js_output_path)
else:
log.warning('localsearch: Missing search plugin. You must add both search and localsearch to the list of plugins in mkdocs.yml.')
def _build_page(page, config, site_navigation, env, dirty=False):
""" Build a Markdown page and pass to theme template. """
# Run the `pre_page` plugin event
page = config['plugins'].run_event(
'pre_page', page, config=config, site_navigation=site_navigation
)
page.read_source(config=config)
# Run `page_markdown` plugin events.
page.markdown = config['plugins'].run_event(
'page_markdown', page.markdown, page=page, config=config, site_navigation=site_navigation
)
page.render(config, site_navigation)
# Run `page_content` plugin events.
page.content = config['plugins'].run_event(
'page_content', page.content, page=page, config=config, site_navigation=site_navigation
)
context = get_context(site_navigation, config, page)
# Allow 'template:' override in md source files.
if 'template' in page.meta:
template = env.get_template(page.meta['template'])
else:
template = env.get_template('main.html')
# Run `page_context` plugin events.
context = config['plugins'].run_event(
'page_context', context, page=page, config=config, site_navigation=site_navigation
)
# Render the template.
output_content = template.render(context)
# Run `post_page` plugin events.
output_content = config['plugins'].run_event(
'post_page', output_content, page=page, config=config
)
# Write the output file.
if output_content.strip():
utils.write_file(output_content.encode('utf-8'), page.abs_output_path)
else:
log.info("Page skipped: '{}'. Generated empty output.".format(page.title))
def _build_page(page, config, site_navigation, env, dump_json):
# Read the input file
input_path = os.path.join(config['docs_dir'], page.input_path)
try:
input_content = io.open(input_path, 'r', encoding='utf-8').read()
except IOError:
log.error('file not found: %s', input_path)
raise
# Process the markdown text
html_content, table_of_contents, meta = convert_markdown(
markdown_source=input_content,
config=config,
site_navigation=site_navigation
)
context = get_global_context(site_navigation, config)
context.update(get_page_context(
page, html_content, table_of_contents, meta, config
))
# Allow 'template:' override in md source files.
if 'template' in meta:
template = env.get_template(meta['template'][0])
else:
template = env.get_template('base.html')
# Render the template.
output_content = template.render(context)
# Write the output file.
output_path = os.path.join(config['site_dir'], page.output_path)
if dump_json:
json_context = {
'content': context['content'],
'title': context['current_page'].title,
'url': context['current_page'].abs_url,
'language': 'en',
}
json_output = json.dumps(json_context, indent=4).encode('utf-8')
utils.write_file(json_output, output_path.replace('.html', '.json'))
else:
utils.write_file(output_content.encode('utf-8'), output_path)
return html_content, table_of_contents, meta
def build_pages(config, dump_json=False):
"""
Builds all the pages and writes them into the build directory.
"""
site_navigation = nav.SiteNavigation(config["pages"], config["use_directory_urls"])
loader = jinja2.FileSystemLoader(config["theme_dir"])
env = jinja2.Environment(loader=loader)
build_404(config, env, site_navigation)
for page in site_navigation.walk_pages():
# Read the input file
input_path = os.path.join(config["docs_dir"], page.input_path)
input_content = open(input_path, "r").read()
if PY2:
input_content = input_content.decode("utf-8")
# Process the markdown text
html_content, table_of_contents, meta = convert_markdown(
input_content, extensions=config["markdown_extensions"]
)
html_content = post_process_html(html_content, site_navigation)
context = get_global_context(site_navigation, config)
context.update(get_page_context(page, html_content, site_navigation, table_of_contents, meta, config))
# Allow 'template:' override in md source files.
if "template" in meta:
template = env.get_template(meta["template"][0])
else:
template = env.get_template("base.html")
# Render the template.
output_content = template.render(context)
# Write the output file.
output_path = os.path.join(config["site_dir"], page.output_path)
if dump_json:
json_context = {
"content": context["content"],
"title": context["current_page"].title,
"url": context["current_page"].abs_url,
"language": "en",
}
utils.write_file(json.dumps(json_context, indent=4).encode("utf-8"), output_path.replace(".html", ".json"))
else:
utils.write_file(output_content.encode("utf-8"), output_path)
def _build_page(page, config, site_navigation, env, dump_json):
# Read the input file
input_path = os.path.join(config['docs_dir'], page.input_path)
try:
input_content = io.open(input_path, 'r', encoding='utf-8').read()
except IOError:
log.error('file not found: %s', input_path)
raise
# Process the markdown text
html_content, table_of_contents, meta = convert_markdown(
markdown_source=input_content,
config=config,
site_navigation=site_navigation
)
context = get_global_context(site_navigation, config)
context.update(get_page_context(
page, html_content, table_of_contents, meta, config
))
# Allow 'template:' override in md source files.
if 'template' in meta:
template = env.get_template(meta['template'][0])
else:
template = env.get_template('base.html')
# Render the template.
output_content = template.render(context)
# Write the output file.
output_path = os.path.join(config['site_dir'], page.output_path)
if dump_json:
json_context = {
'content': context['content'],
'title': context['current_page'].title,
'url': context['current_page'].abs_url,
'language': 'en',
}
json_output = json.dumps(json_context, indent=4).encode('utf-8')
utils.write_file(json_output, output_path.replace('.html', '.json'))
else:
utils.write_file(output_content.encode('utf-8'), output_path)
return html_content, table_of_contents, meta
def build_template(template_name, env, config, site_navigation=None):
log.debug("Building template: %s", template_name)
try:
template = env.get_template(template_name)
except TemplateNotFound:
return False
context = {'page': None}
if site_navigation is not None:
context.update(get_global_context(site_navigation, config))
output_content = template.render(context)
output_path = os.path.join(config['site_dir'], template_name)
utils.write_file(output_content.encode('utf-8'), output_path)
return True
def _build_page(page, config, files, nav, env, dirty=False):
""" Pass a Page to theme template and write output to site_dir. """
try:
# When --dirty is used, only build the page if the file has been modified since the
# previous build of the output.
if dirty and not page.file.is_modified():
return
log.debug("Building page {}".format(page.file.src_path))
# Activate page. Signals to theme that this is the current page.
page.active = True
context = get_context(nav, files, config, page)
# Allow 'template:' override in md source files.
if 'template' in page.meta:
template = env.get_template(page.meta['template'])
else:
template = env.get_template('main.html')
# Run `page_context` plugin events.
context = config['plugins'].run_event(
'page_context', context, page=page, config=config, nav=nav
)
# Render the template.
output = template.render(context)
# Run `post_page` plugin events.
output = config['plugins'].run_event(
'post_page', output, page=page, config=config
)
# Write the output file.
if output.strip():
utils.write_file(output.encode('utf-8', errors='xmlcharrefreplace'), page.file.abs_dest_path)
else:
log.info("Page skipped: '{}'. Generated empty output.".format(page.file.src_path))
# Deactivate page
page.active = False
except Exception as e:
log.error("Error building page '{}': {}".format(page.file.src_path, e))
raise
def build_template(template_name, env, config, site_navigation=None):
log.debug("Building template: %s", template_name)
try:
template = env.get_template(template_name)
except TemplateNotFound:
return False
context = {'page': None}
if site_navigation is not None:
context.update(get_global_context(site_navigation, config))
output_content = template.render(context)
output_path = os.path.join(config['site_dir'], template_name)
utils.write_file(output_content.encode('utf-8'), output_path)
return True
def build_template(template_name, env, config, site_navigation=None):
""" Build a template using the theme environment. """
log.debug("Building template: %s", template_name)
try:
template = env.get_template(template_name)
except TemplateNotFound:
log.info("Template skipped: '{}'. Not found in template directories.".
format(template_name))
return
# Run `pre_template` plugin events.
template = config['plugins'].run_event('pre_template',
template,
template_name=template_name,
config=config)
context = get_context(site_navigation, config)
# Run `template_context` plugin events.
context = config['plugins'].run_event('template_context',
context,
template_name=template_name,
config=config)
output_content = template.render(context)
# Run `post_template` plugin events.
output_content = config['plugins'].run_event('post_template',
output_content,
template_name=template_name,
config=config)
if output_content.strip():
output_path = os.path.join(config['site_dir'], template_name)
utils.write_file(output_content.encode('utf-8'), output_path)
if template_name == 'sitemap.xml':
log.debug("Gzipping template: %s", template_name)
with gzip.open('{}.gz'.format(output_path), 'wb') as f:
f.write(output_content.encode('utf-8'))
else:
log.info("Template skipped: '{}'. Generated empty output.".format(
template_name))
def build_extra_templates(extra_templates, config, site_navigation=None):
log.debug("Building extra_templates page")
for extra_template in extra_templates:
input_path = os.path.join(config['docs_dir'], extra_template)
with io.open(input_path, 'r', encoding='utf-8') as template_file:
template = jinja2.Template(template_file.read())
context = {'page': None}
if site_navigation is not None:
context.update(get_global_context(site_navigation, config))
output_content = template.render(context)
output_path = os.path.join(config['site_dir'], extra_template)
utils.write_file(output_content.encode('utf-8'), output_path)
def build_extra_templates(extra_templates, config, site_navigation=None):
log.debug("Building extra_templates page")
for extra_template in extra_templates:
input_path = os.path.join(config['docs_dir'], extra_template)
with io.open(input_path, 'r', encoding='utf-8') as template_file:
template = jinja2.Template(template_file.read())
context = {'page': None}
if site_navigation is not None:
context.update(get_global_context(site_navigation, config))
output_content = template.render(context)
output_path = os.path.join(config['site_dir'], extra_template)
utils.write_file(output_content.encode('utf-8'), output_path)
def build_template(template_name, env, config, site_navigation=None, extra_context=None):
try:
template = env.get_template(template_name)
except TemplateNotFound:
return False
if site_navigation is not None:
context = get_global_context(site_navigation, config)
else:
context = {}
if extra_context is not None:
context.update(extra_context)
output_content = template.render(context)
output_path = os.path.join(config['site_dir'], template_name)
utils.write_file(output_content.encode('utf-8'), output_path)
return True
def build_extra_templates(extra_templates, config, site_navigation=None):
""" Build user templates which are not part of the theme. """
log.debug("Building extra_templates pages")
for extra_template in extra_templates:
input_path = os.path.join(config['docs_dir'], extra_template)
with io.open(input_path, 'r', encoding='utf-8') as template_file:
template = jinja2.Template(template_file.read())
# Run `pre_template` plugin events.
template = config['plugins'].run_event('pre_template',
template,
template_name=extra_template,
config=config)
context = get_context(site_navigation, config)
# Run `template_context` plugin events.
context = config['plugins'].run_event('template_context',
context,
template_name=extra_template,
config=config)
output_content = template.render(context)
# Run `post_template` plugin events.
output_content = config['plugins'].run_event(
'post_template',
output_content,
template_name=extra_template,
config=config)
if output_content.strip():
output_path = os.path.join(config['site_dir'], extra_template)
utils.write_file(output_content.encode('utf-8'), output_path)
else:
log.info("Template skipped: '{}'. Generated empty output.".format(
extra_template))
def build_template(template_name, env, config, site_navigation=None):
""" Build a template using the theme environment. """
log.debug("Building template: %s", template_name)
try:
template = env.get_template(template_name)
except TemplateNotFound:
log.info("Template skipped: '{}'. Not found in template directories.".format(template_name))
return
# Run `pre_template` plugin events.
template = config['plugins'].run_event(
'pre_template', template, template_name=template_name, config=config
)
context = get_context(site_navigation, config)
# Run `template_context` plugin events.
context = config['plugins'].run_event(
'template_context', context, template_name=template_name, config=config
)
output_content = template.render(context)
# Run `post_template` plugin events.
output_content = config['plugins'].run_event(
'post_template', output_content, template_name=template_name, config=config
)
if output_content.strip():
output_path = os.path.join(config['site_dir'], template_name)
utils.write_file(output_content.encode('utf-8'), output_path)
if template_name == 'sitemap.xml':
log.debug("Gzipping template: %s", template_name)
with gzip.open('{}.gz'.format(output_path), 'wb') as f:
f.write(output_content.encode('utf-8'))
else:
log.info("Template skipped: '{}'. Generated empty output.".format(template_name))
def on_post_build(self, config, **kwargs):
"Build search index."
output_base_path = os.path.join(config['site_dir'], 'search')
search_index = self.search_index.generate_search_index()
json_output_path = os.path.join(output_base_path, 'search_index.json')
utils.write_file(search_index.encode('utf-8'), json_output_path)
if not ('search_index_only' in config['theme'] and config['theme']['search_index_only']):
# Include language support files in output. Copy them directly
# so that only the needed files are included.
files = []
if len(self.config['lang']) > 1 or 'en' not in self.config['lang']:
files.append('lunr.stemmer.support.js')
if len(self.config['lang']) > 1:
files.append('lunr.multi.js')
for lang in self.config['lang']:
if (lang != 'en'):
files.append('lunr.{}.js'.format(lang))
for filename in files:
from_path = os.path.join(base_path, 'lunr-language', filename)
to_path = os.path.join(output_base_path, filename)
utils.copy_file(from_path, to_path)
def _build_extra_template(template_name, files, config, nav):
""" Build user templates which are not part of the theme. """
log.debug("Building extra template: {}".format(template_name))
file = files.get_file_from_path(template_name)
if file is None:
log.warn("Template skipped: '{}' not found in docs_dir.".format(template_name))
return
try:
with io.open(file.abs_src_path, 'r', encoding='utf-8', errors='strict') as f:
template = jinja2.Template(f.read())
except Exception as e:
log.warn("Error reading template '{}': {}".format(template_name, e))
return
output = _build_template(template_name, template, files, config, nav)
if output.strip():
utils.write_file(output.encode('utf-8'), file.abs_dest_path)
else:
log.info("Template skipped: '{}' generated empty output.".format(template_name))
def build_template(template_name,
env,
config,
site_navigation=None,
extra_context=None):
try:
template = env.get_template(template_name)
except TemplateNotFound:
return False
if site_navigation is not None:
context = get_global_context(site_navigation, config)
else:
context = {}
if extra_context is not None:
context.update(extra_context)
output_content = template.render(context)
output_path = os.path.join(config['site_dir'], template_name)
utils.write_file(output_content.encode('utf-8'), output_path)
return True
def _build_theme_template(template_name, env, files, config, nav):
""" Build a template using the theme environment. """
log.debug("Building theme template: {}".format(template_name))
try:
template = env.get_template(template_name)
except TemplateNotFound:
log.warn("Template skipped: '{}' not found in theme directories.".format(template_name))
return
output = _build_template(template_name, template, files, config, nav)
if output.strip():
output_path = os.path.join(config['site_dir'], template_name)
utils.write_file(output.encode('utf-8'), output_path)
if template_name == 'sitemap.xml':
log.debug("Gzipping template: %s", template_name)
with gzip.open('{}.gz'.format(output_path), 'wb') as f:
f.write(output.encode('utf-8'))
else:
log.info("Template skipped: '{}' generated empty output.".format(template_name))
def build_pages(config):
"""
Builds all the pages and writes them into the build directory.
"""
site_navigation = nav.SiteNavigation(config['pages'])
loader = jinja2.FileSystemLoader(config['theme_dir'])
env = jinja2.Environment(loader=loader)
for page in site_navigation.walk_pages():
# Read the input file
input_path = os.path.join(config['docs_dir'], page.input_path)
input_content = open(input_path, 'r').read().decode('utf-8')
# Process the markdown text
html_content, table_of_contents, meta = convert_markdown(input_content)
# Replace links ending in .md with links to the generated HTML instead
html_content = re.sub(r'a href="([^"]*\.md)"', PathToURL(config), html_content)
html_content = re.sub('<pre>', '<pre class="prettyprint well">', html_content)
context = get_context(
page, html_content, site_navigation,
table_of_contents, meta, config
)
# Allow 'template:' override in md source files.
if 'template' in meta:
template = env.get_template(meta['template'][0])
else:
template = env.get_template('base.html')
# Render the template.
output_content = template.render(context)
# Write the output file.
output_path = os.path.join(config['site_dir'], page.output_path)
utils.write_file(output_content.encode('utf-8'), output_path)
def build_extra_templates(extra_templates, config, site_navigation=None):
""" Build user templates which are not part of the theme. """
log.debug("Building extra_templates pages")
for extra_template in extra_templates:
input_path = os.path.join(config['docs_dir'], extra_template)
with io.open(input_path, 'r', encoding='utf-8') as template_file:
template = jinja2.Template(template_file.read())
# Run `pre_template` plugin events.
template = config['plugins'].run_event(
'pre_template', template, template_name=extra_template, config=config
)
context = get_context(site_navigation, config)
# Run `template_context` plugin events.
context = config['plugins'].run_event(
'template_context', context, template_name=extra_template, config=config
)
output_content = template.render(context)
# Run `post_template` plugin events.
output_content = config['plugins'].run_event(
'post_template', output_content, template_name=extra_template, config=config
)
if output_content.strip():
output_path = os.path.join(config['site_dir'], extra_template)
utils.write_file(output_content.encode('utf-8'), output_path)
else:
log.info("Template skipped: '{}'. Generated empty output.".format(extra_template))
def on_post_build(self, config, **kwargs):
"Build search index."
output_base_path = os.path.join(config['site_dir'], 'search')
if self.config['local_search_shim']:
print(
"INFO - local_search_shim Enabled! Make sure you've added shims/fetch_shim.js to your docs folder."
)
# Change the search_index from being pure JSON to being JavaScript containing a global searchIndex variable with the JSON object we want
# Also write it in the traditional format, so that either way works
search_index = self.search_index.generate_search_index()
search_index_shimmed = "shim_localSearchIndex = " + search_index
json_output_path = os.path.join(output_base_path,
'search_index.json')
json_output_path_shimmed = os.path.join(output_base_path,
'search_index.js')
utils.write_file(search_index.encode('utf-8'), json_output_path)
utils.write_file(search_index_shimmed.encode('utf-8'),
json_output_path_shimmed)
else:
# Write the search index only in the traditional way
print(
"INFO - local_search_shim disabled. Generating only traditional JSON search index..."
)
search_index = self.search_index.generate_search_index()
json_output_path = os.path.join(output_base_path,
'search_index.json')
utils.write_file(search_index.encode('utf-8'), json_output_path)
if not ('search_index_only' in config['theme']
and config['theme']['search_index_only']):
# Include language support files in output. Copy them directly
# so that only the needed files are included.
files = []
if len(self.config['lang']) > 1 or 'en' not in self.config['lang']:
files.append('lunr.stemmer.support.js')
if len(self.config['lang']) > 1:
files.append('lunr.multi.js')
for lang in self.config['lang']:
if (lang != 'en'):
files.append('lunr.{}.js'.format(lang))
for filename in files:
from_path = os.path.join(base_path, 'lunr-language', filename)
to_path = os.path.join(output_base_path, filename)
utils.copy_file(from_path, to_path)
def build_pages(config, dump_json=False, dirty=False):
"""
Builds all the pages and writes them into the build directory.
"""
site_navigation = nav.SiteNavigation(config['pages'], config['use_directory_urls'])
loader = jinja2.FileSystemLoader(config['theme_dir'] + [config['mkdocs_templates'], ])
env = jinja2.Environment(loader=loader)
# TODO: remove DeprecationContext in v1.0 when all deprecated vars have been removed
from jinja2.runtime import Context
deprecated_vars = [
'page_title',
'content',
'toc',
'meta',
'current_page',
'canonical_url',
'previous_page',
'next_page'
]
class DeprecationContext(Context):
def resolve(self, key):
""" Log a warning when acessing any deprecated variable name. """
if key in deprecated_vars:
replacement = "page" if key == 'current_page' else "page.{0}".format(key)
log.warn(
"Template variable warning: '{0}' is being deprecated and will not be "
"available in a future version. Use '{1}' instead.".format(key, replacement)
)
return super(DeprecationContext, self).resolve(key)
env.context_class = DeprecationContext
# TODO: end remove DeprecationContext
env.filters['tojson'] = filters.tojson
search_index = search.SearchIndex()
# Force absolute URLs in the nav of error pages and account for the
# possability that the docs root might be different than the server root.
# See https://github.com/mkdocs/mkdocs/issues/77
site_navigation.url_context.force_abs_urls = True
default_base = site_navigation.url_context.base_path
site_navigation.url_context.base_path = utils.urlparse(config['site_url']).path
build_template('404.html', env, config, site_navigation)
# Reset nav behavior to the default
site_navigation.url_context.force_abs_urls = False
site_navigation.url_context.base_path = default_base
if not build_template('search.html', env, config, site_navigation):
log.debug("Search is enabled but the theme doesn't contain a "
"search.html file. Assuming the theme implements search "
"within a modal.")
build_template('sitemap.xml', env, config, site_navigation)
build_extra_templates(config['extra_templates'], config, site_navigation)
# append extra pages not including in [email protected]
append_extra_pages(config, env, dump_json, site_navigation)
for page in site_navigation.walk_pages():
try:
# When --dirty is used, only build the page if the markdown has been modified since the
# previous build of the output.
input_path, output_path = get_complete_paths(config, page)
if dirty and (utils.modified_time(input_path) < utils.modified_time(output_path)):
continue
log.debug("Building page %s", page.input_path)
build_result = _build_page(page, config, site_navigation, env,
dump_json)
html_content, table_of_contents, _ = build_result
search_index.add_entry_from_context(
page, html_content, table_of_contents)
except Exception:
log.error("Error building page %s", page.input_path)
raise
search_index = search_index.generate_search_index()
json_output_path = os.path.join(config['site_dir'], 'mkdocs', 'search_index.json')
utils.write_file(search_index.encode('utf-8'), json_output_path)
def on_post_build(self, config, **kwargs):
"""
The post_build event does not alter any variables. Use this event to call post-build scripts.
See https://www.mkdocs.org/user-guide/plugins/#on_post_build.
"""
if not self.config.get("enabled"):
return
if len(self.context) == 0:
msg = "Could not find a template context.\n"
msg += "Report an issue at https://github.com/timvink/mkdocs-print-site-plugin\n"
msg += f"And mention the template you're using: {get_theme_name(config)}"
raise PluginError(msg)
# Add print-site.js
js_output_base_path = os.path.join(config["site_dir"], "js")
js_file_path = os.path.join(js_output_base_path, "print-site.js")
copy_file(os.path.join(os.path.join(HERE, "js"), "print-site.js"),
js_file_path)
if self.config.get("include_css"):
# Add print-site.css
css_output_base_path = os.path.join(config["site_dir"], "css")
css_file_path = os.path.join(css_output_base_path,
"print-site.css")
copy_file(
os.path.join(os.path.join(HERE, "css"), "print-site.css"),
css_file_path)
# Add enumeration css
for f in self.enum_css_files:
f = f.replace("/", os.sep)
css_file_path = os.path.join(config["site_dir"], f)
copy_file(os.path.join(HERE, f), css_file_path)
# Add theme CSS file
css_file = "print-site-%s.css" % get_theme_name(config)
if css_file in os.listdir(os.path.join(HERE, "css")):
css_file_path = os.path.join(css_output_base_path, css_file)
copy_file(os.path.join(os.path.join(HERE, "css"), css_file),
css_file_path)
# Combine the HTML of all pages present in the navigation
self.print_page.content = self.renderer.write_combined()
# Generate a TOC sidebar for HTML version of print page
self.print_page.toc = self.renderer.get_toc_sidebar()
# Get the info for MkDocs to be able to apply a theme template on our print page
env = config["theme"].get_env()
# env.list_templates()
template = env.get_template("main.html")
self.context["page"] = self.print_page
# Render the theme template for the print page
html = template.render(self.context)
# Remove lazy loading attributes from images
# https://regex101.com/r/HVpKPs/1
html = re.sub(r"(\<img.+)(loading=\"lazy\")", r"\1", html)
# Compatiblity with mkdocs-chart-plugin
# As this plugin adds some javascript to every page
# It should be included in the print site also
if config.get("plugins", {}).get("charts"):
html = (config.get("plugins",
{}).get("charts").add_javascript_variables(
html, self.print_page, config))
# Compatibility with https://github.com/g-provost/lightgallery-markdown
# This plugin insert link hrefs with double dashes, f.e.
# <link href="//assets/css/somecss.css">
# Details https://github.com/timvink/mkdocs-print-site-plugin/issues/68
htmls = html.split("</head>")
base_url = "../" if config.get("use_directory_urls") else ""
htmls[0] = htmls[0].replace("href=\"//", f"href=\"{base_url}")
htmls[0] = htmls[0].replace("src=\"//", f"src=\"{base_url}")
html = "</head>".join(htmls)
# Determine calls to required javascript functions
js_calls = "remove_material_navigation();"
js_calls += "remove_mkdocs_theme_navigation();"
if self.config.get("add_table_of_contents"):
js_calls += "generate_toc();"
# Inject JS into print page
print_site_js = ("""
<script type="text/javascript">
document.addEventListener('DOMContentLoaded', function () {
%s
})
</script>
""" % js_calls)
html = html.replace("</head>", print_site_js + "</head>")
# Write the print_page file to the output folder
write_file(
html.encode("utf-8", errors="xmlcharrefreplace"),
self.print_page.file.abs_dest_path,
)
def build_pages(config, dump_json=False):
"""
Builds all the pages and writes them into the build directory.
"""
site_navigation = nav.SiteNavigation(config['pages'], config['use_directory_urls'])
loader = jinja2.FileSystemLoader(config['theme_dir'])
env = jinja2.Environment(loader=loader)
search_index = search.SearchIndex()
build_template('404.html', env, config, site_navigation)
build_template('search.html', env, config, site_navigation)
nav_pages = []
for page in site_navigation.walk_pages():
nav_pages.append(page.input_path)
# Read the input file
input_path = os.path.join(config['docs_dir'], page.input_path)
input_content = open(input_path, 'r').read()
if PY2:
input_content = input_content.decode('utf-8')
# Process the markdown text
html_content, table_of_contents, meta = convert_markdown(
input_content, site_navigation,
extensions=config['markdown_extensions'], strict=config['strict']
)
context = get_global_context(site_navigation, config)
context.update(get_page_context(
page, html_content, site_navigation,
table_of_contents, meta, config
))
# Allow 'template:' override in md source files.
if 'template' in meta:
template = env.get_template(meta['template'][0])
else:
template = env.get_template('base.html')
if not utils.is_markdown_file(page.input_path):
template = env.get_template('base_without_toc.html')
# Render the template.
output_content = template.render(context)
# Write the output file.
output_path = os.path.join(config['site_dir'], page.output_path)
if dump_json:
json_context = {
'content': context['content'],
'title': context['current_page'].title,
'url': context['current_page'].abs_url,
'language': 'en',
}
utils.write_file(json.dumps(json_context, indent=4).encode('utf-8'), output_path.replace('.html', '.json'))
else:
utils.write_file(output_content.encode('utf-8'), output_path)
search_index.add_entry_from_context(page, html_content, table_of_contents)
# generate html for other md files
files = ListFilesByTxt(os.path.join(config['docs_dir']),'.md')
for mdf in files:
title = os.path.basename(mdf)
title = os.path.splitext(title)[0]
path = os.path.relpath(mdf,config['docs_dir'])
url = utils.get_url_path(path,config['use_directory_urls'])
output_path = utils.get_html_path(path)
if(path in nav_pages):continue
input_content = open(mdf, 'r').read()
if PY2:
input_content = input_content.decode('utf-8')
site_navigation.url_context.set_current_url(url)
# Process the markdown text
html_content, table_of_contents, meta = convert_markdown(
input_content, site_navigation,
extensions=config['markdown_extensions']
)
context = get_global_context(site_navigation, config)
page = nav.Page(title=title, url=url,path=path,url_context=site_navigation.url_context)
context.update(get_page_context(
page, html_content, site_navigation,
table_of_contents, meta, config
))
if 'template' in meta:
template = env.get_template(meta['template'][0])
else:
template = env.get_template('base.html')
if not utils.is_markdown_file(mdf):
template = env.get_template('base_without_toc.html')
# Render the template.
output_content = template.render(context)
# Write the output file.
output_path = os.path.join(config['site_dir'], output_path)
utils.write_file(output_content.encode('utf-8'), output_path)
#search_index.add_entry_from_context(page, html_content, table_of_contents)
build_template('js/tipuesearch/tipuesearch_content.js', env, config, extra_context={
'search_index': search_index.generate_search_index()
})
def build_pages(config, dump_json=False):
"""
Builds all the pages and writes them into the build directory.
"""
site_navigation = nav.SiteNavigation(config['pages'],
config['use_directory_urls'])
loader = jinja2.FileSystemLoader(config['theme_dir'])
env = jinja2.Environment(loader=loader)
search_index = search.SearchIndex()
build_template('404.html', env, config, site_navigation)
build_template('search.html', env, config, site_navigation)
nav_pages = []
for page in site_navigation.walk_pages():
nav_pages.append(page.input_path)
# Read the input file
input_path = os.path.join(config['docs_dir'], page.input_path)
input_content = open(input_path, 'r').read()
if PY2:
input_content = input_content.decode('utf-8')
# Process the markdown text
html_content, table_of_contents, meta = convert_markdown(
input_content,
site_navigation,
extensions=config['markdown_extensions'],
strict=config['strict'])
context = get_global_context(site_navigation, config)
context.update(
get_page_context(page, html_content, site_navigation,
table_of_contents, meta, config))
# Allow 'template:' override in md source files.
if 'template' in meta:
template = env.get_template(meta['template'][0])
else:
template = env.get_template('base.html')
if not utils.is_markdown_file(page.input_path):
template = env.get_template('base_without_toc.html')
# Render the template.
output_content = template.render(context)
# Write the output file.
output_path = os.path.join(config['site_dir'], page.output_path)
if dump_json:
json_context = {
'content': context['content'],
'title': context['current_page'].title,
'url': context['current_page'].abs_url,
'language': 'en',
}
utils.write_file(
json.dumps(json_context, indent=4).encode('utf-8'),
output_path.replace('.html', '.json'))
else:
utils.write_file(output_content.encode('utf-8'), output_path)
search_index.add_entry_from_context(page, html_content,
table_of_contents)
# generate html for other md files
files = ListFilesByTxt(os.path.join(config['docs_dir']), '.md')
for mdf in files:
title = os.path.basename(mdf)
title = os.path.splitext(title)[0]
path = os.path.relpath(mdf, config['docs_dir'])
url = utils.get_url_path(path, config['use_directory_urls'])
output_path = utils.get_html_path(path)
if (path in nav_pages): continue
input_content = open(mdf, 'r').read()
if PY2:
input_content = input_content.decode('utf-8')
site_navigation.url_context.set_current_url(url)
# Process the markdown text
html_content, table_of_contents, meta = convert_markdown(
input_content,
site_navigation,
extensions=config['markdown_extensions'])
context = get_global_context(site_navigation, config)
page = nav.Page(title=title,
url=url,
path=path,
url_context=site_navigation.url_context)
context.update(
get_page_context(page, html_content, site_navigation,
table_of_contents, meta, config))
if 'template' in meta:
template = env.get_template(meta['template'][0])
else:
template = env.get_template('base.html')
if not utils.is_markdown_file(mdf):
template = env.get_template('base_without_toc.html')
# Render the template.
output_content = template.render(context)
# Write the output file.
output_path = os.path.join(config['site_dir'], output_path)
utils.write_file(output_content.encode('utf-8'), output_path)
#search_index.add_entry_from_context(page, html_content, table_of_contents)
build_template(
'js/tipuesearch/tipuesearch_content.js',
env,
config,
extra_context={'search_index': search_index.generate_search_index()})
def build_pages(config, dump_json=False, dirty=False):
"""
Builds all the pages and writes them into the build directory.
"""
site_navigation = nav.SiteNavigation(config['pages'], config['use_directory_urls'])
loader = jinja2.FileSystemLoader(config['theme_dir'] + [config['mkdocs_templates'], ])
env = jinja2.Environment(loader=loader)
# TODO: remove DeprecationContext in v1.0 when all deprecated vars have been removed
from jinja2.runtime import Context
deprecated_vars = {
'page_title': 'page.title',
'content': 'page.content',
'toc': 'page.toc',
'meta': 'page.meta',
'canonical_url': 'page.canonical_url',
'previous_page': 'page.previous_page',
'next_page': 'page.next_page',
'current_page': 'page',
'include_nav': 'nav|length>1',
'include_next_prev': '(page.next_page or page.previous_page)',
'site_name': 'config.site_name',
'site_author': 'config.site_author',
'page_description': 'config.site_description',
'repo_url': 'config.repo_url',
'repo_name': 'config.repo_name',
'site_url': 'config.site_url',
'copyright': 'config.copyright',
'google_analytics': 'config.google_analytics',
'homepage_url': 'nav.homepage.url',
'favicon': '{{ base_url }}/img/favicon.ico',
}
class DeprecationContext(Context):
def resolve(self, key):
""" Log a warning when accessing any deprecated variable name. """
if key in deprecated_vars:
log.warn(
"Template variable warning: '{0}' is being deprecated "
"and will not be available in a future version. Use "
"'{1}' instead.".format(key, deprecated_vars[key])
)
return super(DeprecationContext, self).resolve(key)
env.context_class = DeprecationContext
# TODO: end remove DeprecationContext
env.filters['tojson'] = filters.tojson
search_index = search.SearchIndex()
# Force absolute URLs in the nav of error pages and account for the
# possability that the docs root might be different than the server root.
# See https://github.com/mkdocs/mkdocs/issues/77
site_navigation.url_context.force_abs_urls = True
default_base = site_navigation.url_context.base_path
site_navigation.url_context.base_path = utils.urlparse(config['site_url']).path
build_template('404.html', env, config, site_navigation)
# Reset nav behavior to the default
site_navigation.url_context.force_abs_urls = False
site_navigation.url_context.base_path = default_base
if not build_template('search.html', env, config, site_navigation):
log.debug("Search is enabled but the theme doesn't contain a "
"search.html file. Assuming the theme implements search "
"within a modal.")
build_template('sitemap.xml', env, config, site_navigation)
build_extra_templates(config['extra_templates'], config, site_navigation)
for page in site_navigation.walk_pages():
try:
# When --dirty is used, only build the page if the markdown has been modified since the
# previous build of the output.
input_path, output_path = get_complete_paths(config, page)
if dirty and (utils.modified_time(input_path) < utils.modified_time(output_path)):
continue
log.debug("Building page %s", page.input_path)
build_result = _build_page(page, config, site_navigation, env,
dump_json)
html_content, table_of_contents, _ = build_result
search_index.add_entry_from_context(
page, html_content, table_of_contents)
except Exception:
log.error("Error building page %s", page.input_path)
raise
search_index = search_index.generate_search_index()
json_output_path = os.path.join(config['site_dir'], 'mkdocs', 'search_index.json')
utils.write_file(search_index.encode('utf-8'), json_output_path)
def on_post_build(self, config):
"""
The post_build event does not alter any variables. Use this event to call post-build scripts.
See https://www.mkdocs.org/user-guide/plugins/#on_post_build.
"""
# Add print-site.js
js_output_base_path = os.path.join(config["site_dir"], "js")
js_file_path = os.path.join(js_output_base_path, "print-site.js")
copy_file(os.path.join(os.path.join(HERE, "js"), "print-site.js"),
js_file_path)
# Add print-site.css
css_output_base_path = os.path.join(config["site_dir"], "css")
css_file_path = os.path.join(css_output_base_path, "print-site.css")
copy_file(os.path.join(os.path.join(HERE, "css"), "print-site.css"),
css_file_path)
# Add theme CSS file
css_file = "print-site-%s.css" % get_theme_name(config)
if css_file in os.listdir(os.path.join(HERE, "css")):
css_file_path = os.path.join(css_output_base_path, css_file)
copy_file(os.path.join(os.path.join(HERE, "css"), css_file),
css_file_path)
# Determine calls to required javascript functions
js_calls = ""
if self.config.get("add_table_of_contents"):
js_calls += "generate_toc();"
# Add JS file for compatibility for mkdocs-material instant loading
# note this is inserted to all mkdocs pages,
# because each page can be the start of instant loading session
js_instant_loading = ("""
// Subscribe functions for compatibility
// with mkdocs-material's instant loading feature
if (
typeof app !== "undefined" &&
typeof app.document$ !== "undefined"
) {
app.document$.subscribe(function() {
if ( document.querySelector("#print-site-page") !== null ) {
%s
}
})
}
""" % js_calls)
write_file(
js_instant_loading.encode("utf-8", errors="xmlcharrefreplace"),
os.path.join(js_output_base_path, "print-site-instant-loading.js"),
)
# Combine the HTML of all pages present in the navigation
self.print_page.content = self.renderer.write_combined()
# Get the info for MkDocs to be able to apply a theme template on our print page
env = config["theme"].get_env()
template = env.get_template("main.html")
self.context["page"] = self.print_page
# Render the theme template for the print page
html = template.render(self.context)
# Inject JS into print page
print_site_js = ("""
<script type="text/javascript">
window.addEventListener('load', function () {
%s
})
</script>
""" % js_calls)
html = html.replace("</body>", print_site_js + "</body>")
# Write the print_page file to the output folder
write_file(
html.encode("utf-8", errors="xmlcharrefreplace"),
self.print_page.file.abs_dest_path,
)
def build_pages(config, dump_json=False):
"""
Builds all the pages and writes them into the build directory.
"""
site_navigation = nav.SiteNavigation(config['pages'],
config['use_directory_urls'])
loader = jinja2.FileSystemLoader(config['theme_dir'] + [
config['mkdocs_templates'],
])
env = jinja2.Environment(loader=loader)
# TODO: remove DeprecationContext in v1.0 when all deprecated vars have been removed
from jinja2.runtime import Context
deprecated_vars = [
'page_title', 'content', 'toc', 'meta', 'current_page',
'canonical_url', 'previous_page', 'next_page'
]
class DeprecationContext(Context):
def resolve(self, key):
""" Log a warning when acessing any deprecated variable name. """
if key in deprecated_vars:
replacement = "page" if key == 'current_page' else "page.{0}".format(
key)
log.warn(
"Template variable warning: '{0}' is being deprecated and will not be "
"available in a future version. Use '{1}' instead.".format(
key, replacement))
return super(DeprecationContext, self).resolve(key)
env.context_class = DeprecationContext
# TODO: end remove DeprecationContext
env.filters['tojson'] = filters.tojson
search_index = search.SearchIndex()
build_template('404.html', env, config, site_navigation)
if not build_template('search.html', env, config, site_navigation):
log.debug("Search is enabled but the theme doesn't contain a "
"search.html file. Assuming the theme implements search "
"within a modal.")
build_template('sitemap.xml', env, config, site_navigation)
build_extra_templates(config['extra_templates'], config, site_navigation)
for page in site_navigation.walk_pages():
try:
log.debug("Building page %s", page.input_path)
build_result = _build_page(page, config, site_navigation, env,
dump_json)
html_content, table_of_contents, _ = build_result
search_index.add_entry_from_context(page, html_content,
table_of_contents)
except Exception:
log.error("Error building page %s", page.input_path)
raise
search_index = search_index.generate_search_index()
json_output_path = os.path.join(config['site_dir'], 'mkdocs',
'search_index.json')
utils.write_file(search_index.encode('utf-8'), json_output_path)
def build_pages(config, dump_json=False):
"""
Builds all the pages and writes them into the build directory.
"""
site_navigation = nav.SiteNavigation(config['pages'],
config['use_directory_urls'])
loader = jinja2.FileSystemLoader(config['theme_dir'])
env = jinja2.Environment(loader=loader)
search_index = search.SearchIndex()
build_template('404.html', env, config, site_navigation)
if config['include_search']:
if not build_template('search.html', env, config, site_navigation):
log.debug("Search is enabled but the theme doesn't contain a "
"search.html file. Assuming the theme implements search "
"within a modal.")
for page in site_navigation.walk_pages():
# Read the input file
input_path = os.path.join(config['docs_dir'], page.input_path)
try:
input_content = open(input_path, 'r').read()
except IOError:
log.error('file not found: %s' % input_path)
if PY2:
input_content = input_content.decode('utf-8')
# Process the markdown text
html_content, table_of_contents, meta = convert_markdown(
input_content,
site_navigation,
extensions=config['markdown_extensions'],
strict=config['strict'])
context = get_global_context(site_navigation, config)
context.update(
get_page_context(page, html_content, site_navigation,
table_of_contents, meta, config))
# Allow 'template:' override in md source files.
if 'template' in meta:
template = env.get_template(meta['template'][0])
else:
template = env.get_template('base.html')
# Render the template.
output_content = template.render(context)
# Write the output file.
output_path = os.path.join(config['site_dir'], page.output_path)
if dump_json:
json_context = {
'content': context['content'],
'title': context['current_page'].title,
'url': context['current_page'].abs_url,
'language': 'en',
}
utils.write_file(
json.dumps(json_context, indent=4).encode('utf-8'),
output_path.replace('.html', '.json'))
else:
utils.write_file(output_content.encode('utf-8'), output_path)
search_index.add_entry_from_context(page, html_content,
table_of_contents)
if config['include_search']:
search_index = search_index.generate_search_index()
json_output_path = os.path.join(config['site_dir'], 'mkdocs', 'js',
'tipuesearch_content.json')
utils.write_file(search_index.encode('utf-8'), json_output_path)
build_template('mkdocs/js/tipuesearch_content.js',
env,
config,
extra_context={'search_index': search_index})
def on_post_build(self, config, **kwargs):
"Build search index."
search_index = self.search_index.generate_search_index()
json_output_path = os.path.join(config['site_dir'], 'search', 'search_index.json')
utils.write_file(search_index.encode('utf-8'), json_output_path)
def build_pages(config, dump_json=False):
"""
Builds all the pages and writes them into the build directory.
"""
site_navigation = nav.SiteNavigation(config['pages'], config['use_directory_urls'])
loader = jinja2.FileSystemLoader(config['theme_dir'] + [config['mkdocs_templates'], ])
env = jinja2.Environment(loader=loader)
# TODO: remove DeprecationContext in v1.0 when all deprecated vars have been removed
from jinja2.runtime import Context
deprecated_vars = [
'page_title',
'content',
'toc',
'meta',
'current_page',
'canonical_url',
'previous_page',
'next_page'
]
class DeprecationContext(Context):
def resolve(self, key):
""" Log a warning when acessing any deprecated variable name. """
if key in deprecated_vars:
replacement = "page" if key == 'current_page' else "page.{0}".format(key)
log.warn(
"Template variable warning: '{0}' is being deprecated and will not be "
"available in a future version. Use '{1}' instead.".format(key, replacement)
)
return super(DeprecationContext, self).resolve(key)
env.context_class = DeprecationContext
# TODO: end remove DeprecationContext
env.filters['tojson'] = filters.tojson
search_index = search.SearchIndex()
build_template('404.html', env, config, site_navigation)
if not build_template('search.html', env, config, site_navigation):
log.debug("Search is enabled but the theme doesn't contain a "
"search.html file. Assuming the theme implements search "
"within a modal.")
build_template('sitemap.xml', env, config, site_navigation)
build_extra_templates(config['extra_templates'], config, site_navigation)
for page in site_navigation.walk_pages():
try:
log.debug("Building page %s", page.input_path)
build_result = _build_page(page, config, site_navigation, env,
dump_json)
html_content, table_of_contents, _ = build_result
search_index.add_entry_from_context(
page, html_content, table_of_contents)
except Exception:
log.error("Error building page %s", page.input_path)
raise
search_index = search_index.generate_search_index()
json_output_path = os.path.join(config['site_dir'], 'mkdocs', 'search_index.json')
utils.write_file(search_index.encode('utf-8'), json_output_path)
def wrapper(self, *args):
with TemporaryDirectory(**kw) as td:
for path, content in files.items():
pth = os.path.join(td, path)
utils.write_file(content.encode(encoding='utf-8'), pth)
return fn(self, td, *args)
