Overcoming Unknown Tag Related Errors in MkDocs

on

Photo by Sigmund on Unsplash


When working with MkDocs, if you run into an error that reads "Encountered unknown tag...", it will be a showstopper because the error will block the MkDocs build from proceeding any further. Let's see how you can fix such errors.

Follow the instructions below to fix such an error:

  1. Navigate to the respective page that is indicated in the error message.

  2. Check for code blocks that have special characters in the page and identify the exact code that is causing this error.
    Example:
    {%c}

  3. Fix the issue by escaping those characters.
    You can do this by adding such code within {% raw %} and {% endraw %} 
    Example:
    {% raw %}{%c}{% endraw %}

Example

The following is an example of such an error.

ERROR   -  Error reading page 'integrate/develop/monitoring-service-level-logs.md': Encountered unknown tag 'c'. 
[E 211029 19:57:53 ioloop:907] Exception in callback <bound method LiveReloadHandler.poll_tasks of <class 'livereload.handlers.LiveReloadHandler'>>
    Traceback (most recent call last):
      File "/usr/local/lib/python3.9/site-packages/tornado/ioloop.py", line 905, in _run
        return self.callback()
      File "/usr/local/lib/python3.9/site-packages/livereload/handlers.py", line 69, in poll_tasks
        filepath, delay = cls.watcher.examine()
      File "/usr/local/lib/python3.9/site-packages/livereload/watcher.py", line 119, in examine
        func()
      File "/usr/local/lib/python3.9/site-packages/mkdocs/commands/serve.py", line 114, in builder
        build(config, live_server=live_server, dirty=dirty)
      File "/usr/local/lib/python3.9/site-packages/mkdocs/commands/build.py", line 274, in build
        _populate_page(file.page, config, files, dirty)
      File "/usr/local/lib/python3.9/site-packages/mkdocs/commands/build.py", line 173, in _populate_page
        page.markdown = config['plugins'].run_event(
      File "/usr/local/lib/python3.9/site-packages/mkdocs/plugins.py", line 94, in run_event
        result = method(item, **kwargs)
      File "/usr/local/lib/python3.9/site-packages/markdownextradata/plugin.py", line 59, in on_page_markdown
        md_template = Template(markdown)
      File "/usr/local/lib/python3.9/site-packages/jinja2/environment.py", line 1031, in __new__
        return env.from_string(source, template_class=cls)
      File "/usr/local/lib/python3.9/site-packages/jinja2/environment.py", line 941, in from_string
        return cls.from_code(self, self.compile(source), globals, None)
      File "/usr/local/lib/python3.9/site-packages/jinja2/environment.py", line 638, in compile
        self.handle_exception(source=source_hint)
      File "/usr/local/lib/python3.9/site-packages/jinja2/environment.py", line 832, in handle_exception
        reraise(*rewrite_traceback_stack(source=source))
      File "/usr/local/lib/python3.9/site-packages/jinja2/_compat.py", line 28, in reraise
        raise value.with_traceback(tb)
      File "<unknown>", line 22, in template
    jinja2.exceptions.TemplateSyntaxError: Encountered unknown tag 'c'.

In the above error it says that it has encountered an unknown tag 'c'. When checking the mentioned file, on closer inspection, I noticed that the {%c} in the following line was causing the error. Strangely enough none of the lines mentioned in the error message mapped to the actual line that was causing this error.

appender.SQ_PROXY_APPENDER.layout.pattern = TID: [%d] %5p {%c} [%logger] - %m%ex%n

After I updated the line of code as follows in the page and saved the file, the build proceeded without any further errors.

appender.SQ_PROXY_APPENDER.layout.pattern = TID: [%d] %5p {% raw %}{%c}{% endraw %} [%logger] - %m%ex%n

Comments

Post a Comment