search

lukasgeiter / mkdocs-awesome-pages-plugin

An MkDocs plugin that simplifies configuring page titles and their order
MIT License
453 stars 35 forks source link

Arrange entry "templates" is invalid #25

Closed connerxyz closed 3 years ago

connerxyz commented 3 years ago

I have a portion of my site I'd like to use to document templates (things we create as part of our project not anything to do with MkDocs itself).

The site build breaks when I list 'templates' under arrange in the docs/.pages file.

arrange:
    - index.md
    - ...
    - templates
INFO    -  Cleaning site directory
--
243 | INFO    -  Building documentation to directory: /codebuild/...
244 | Traceback (most recent call last):
245 | File "/codebuild/.../mkdocs_awesome_pages_plugin/navigation.py", line 72, in _arrange_items
246 | return arrange(items, meta.arrange, lambda item: basename(self._get_item_path(item)))
247 | File "/codebuild/.../mkdocs_awesome_pages_plugin/arrange.py", line 29, in arrange
248 | raise InvalidArrangeEntry(entry)
249 | mkdocs_awesome_pages_plugin.arrange.InvalidArrangeEntry: Arrange entry "templates" is invalid.

Is this "invalid" because it's conflicting with potential MkDocs templates? Is there a workaround?

lukasgeiter commented 3 years ago

The arrange option only works with entries that are known to MkDocs and appear in the navigation. Since templates doesn't have to do anything with MkDocs, maybe you can just omit it from the pages file?

connerxyz commented 3 years ago

The site needs to have a templates section, so I can't just omit it from pages file.

That templates section is listed, just like the other sections, but the site won't build when there's a section called "templates".

I'm trying to figure out how I can have a templates section in the site.

arrange:
    - index.md
    - ...
    - services      # works fine
    - templates   # breaks build
lukasgeiter commented 3 years ago

The arrange option does not allow you to add entries to the MkDocs navigation, it can merely change their order.

I'm planning to implement a more powerful version of the feature in the future and I'll take this requirement in consideration.

connerxyz commented 3 years ago

But it works if I use "templates+" and not when I use "templates"... I'm not sure we are talking about the same thing. I'm digging through the plugin source right now.

lukasgeiter commented 3 years ago

Hmm that's interesting. Could you provide me with a minimal example to reproduce the problem?

connerxyz commented 3 years ago

Yes. See here https://github.com/connerxyz/templates-issue-example

connerxyz commented 3 years ago

And then here's the working version. https://github.com/connerxyz/templates-issue-example/tree/working-version

connerxyz commented 3 years ago

It's like MkDocs removes docs/templates directory before building.

connerxyz commented 3 years ago

Possibly related https://github.com/lukasgeiter/mkdocs-awesome-pages-plugin/issues/25

lukasgeiter commented 3 years ago

Thanks for the example. We were indeed not talking about the same thing. I thought that your templates directory didn't contain any markdown files...

As you have seem to figured out by now as well, MkDocs is not including docs/templates when building. Why that is I don't know. I just know that it is unrelated to this plugin, therefore I'll close the issue. Let's see what comes out of issue mkdocs/mkdocs#2185...