Configuring mkdocs plugins from toml

I am trying to configure a plugin for mkdocs, but I’m running into some issues in translating the yaml over to toml. Basically, what I want is to specify something similar to what this yaml snippet does:

plugins:
    - foo:
    - bar
    - search:
        lang: en

But as far as I can tell that won’t work, since TOML does not support mixed type arrays.

I also tried the approach used in configuring the nav-bar (ie. nested tables):

[[tool.portray.mkdocs.plugins.foo]]

[[tool.portray.mkdocs.plugins.bar]]

[[tool.portray.mkdocs.plugins.search]]
lang = "en"

but this failed, since mkdocs appears to expect an array and not a table:

MkDocs[('plugins', ValidationError('Invalid Plugins configuration. Expected a list of plugins'))]
Traceback (most recent call last):
  File "~/.pyenv/versions/3.7.4/bin/portray", line 10, in <module>
    sys.exit(__hug__.cli())
  File "~/.pyenv/versions/3.7.4/lib/python3.7/site-packages/hug/api.py", line 441, in __call__
    result = self.commands.get(command)()
  File "~/.pyenv/versions/3.7.4/lib/python3.7/site-packages/hug/interface.py", line 649, in __call__
    raise exception
  File "~/.pyenv/versions/3.7.4/lib/python3.7/site-packages/hug/interface.py", line 645, in __call__
    result = self.output(self.interface(**pass_to_function), context)
  File "~/.pyenv/versions/3.7.4/lib/python3.7/site-packages/hug/interface.py", line 129, in __call__
    return __hug_internal_self._function(*args, **kwargs)
  File "~/.pyenv/versions/3.7.4/lib/python3.7/site-packages/portray/api.py", line 88, in server
    with render.documentation_in_temp_folder(project_config) as doc_folder:
  File "~/.pyenv/versions/3.7.4ontextlib.py", line 112, in __enter__
    return next(self.gen)
  File "~/.pyenv/versions/3.7.4/lib/python3.7/site-packages/portray/render.py", line 156, in documentation_in_temp_folder
    mkdocs(config["mkdocs"])
  File "~/.pyenv/versions/3.7.4/lib/python3.7/site-packages/portray/render.py", line 70, in mkdocs
    config_instance = _mkdocs_config(config)
  File "~/.pyenv/versions/3.7.4/lib/python3.7/site-packages/portray/render.py", line 169, in _mkdocs_config
    f"Aborted with {len(errors)} Configuration Errors!"
mkdocs.exceptions.ConfigurationError: Aborted with 1 Configuration Errors!```

[dawsonbooth]

@KyleKing I just ran into the same issue. It turns out that TOML doesn’t usually allow multiple separate types and you can’t have

[tool.portray.mkdocs]
markdown_extensions = [
    ...
]

and also

[[tool.portray.mkdocs.markdown_extensions]]
[tool.portray.mkdocs.markdown_extensions."pymdownx.tasklist"]
custom_checkbox = true
clickable_checkbox = false

which is why the poetry check fails. Merging them as you did would work, but portray does not (yet?) handle markdown_extensions with empty properties.

However, portray does have the extra_markdown_extensions property, which I assume is to avoid the multiple type error. I did the following, which passes the poetry check and works for portray!

[tool.portray]
modules = ["MODULE_NAME"]

[[tool.portray.extra_markdown_extensions]]
[tool.portray.extra_markdown_extensions.toc]
permalink = true

[[tool.portray.extra_markdown_extensions]]
[tool.portray.extra_markdown_extensions."pymdownx.highlight"]
linenums = true

[tool.portray.mkdocs]
site_name = "PACKAGE_NAME"
site_url = "https://dawsonbooth.github.io/REPO_NAME/"
edit_uri = "blob/master/"

markdown_extensions = [
    "admonition",
    "codehilite",
    "extra",
    "pymdownx.details",
    "pymdownx.superfences",
]

nav = [{ Overview = "README.md" }]

[tool.portray.mkdocs.theme]
name = "material"
palette = { primary = "blue grey", accent = "red" }

(there’s some extra stuff in there, just pay attention to the use of tool.portray.mkdocs.markdown_extensions and tool.portray.extra_markdown_extensions)

[SamGuay]

Hi @JesseWebDotCom,

I implemented custom slate/light styles in the dcm2bids repo based on whether the person has light vs dark OS. Feel free to peek into the repo.

In short the pyproject.toml looks like this:

[tool.portray.mkdocs]
# Left navigation menu
nav = [{  Home = "README.md"},
       {  "Code of conduct" = "CODE_OF_CONDUCT.md" },
       {  "Contributing" = "CONTRIBUTING.md"},
       {  "1. Usage" = "docs/1-usage.md"},
       {  "2. Tutorial" = "docs/2-tutorial.md"},
       {  "3. Configuration" = "docs/3-configuration.md"},
       {  "4. Advance" = "docs/4-advance.md"},
       {  "Changelog" = "CHANGELOG.md"}]

extra_css = ["docs/stylesheets/extra.css"] # To fix some colors in light vs slate mode.