Hidden files/directories

[pxeger]

Revival of #1738.

Could you consider adding an option to serve hidden static files and templates? I cannot see any reason why one wouldn't want to serve these hidden files, and in particular the .well-known directory is used for a lot of things that one could want in their documentation, including:

• ACME challenges (for Let's Encrypt)
• security.txt
• Keybase Site Verification
• Do-Not-Track policies
• HTTPS Opportunistic Encryption

see https://www.iana.org/assignments/well-known-uris/well-known-uris.xhtml

It would be very useful to have this as a built-in option. A plugin, which could work around this, seems completely unnecessary. Could you explain why this is not enabled, and reconsider the behaviour, or at least add an exception for the well standardised .well-known directory? Or is there a good reason I'm missing not to do this?

[wsmckenz]

This would be useful for me too. My source repos are Azure DevOps wikis. And, by default, they put all the images in a .attachments folder.

[facelessuser]

I imagine there are a bunch of folders/files some consider "well standardized" or common, and I'm sure in the future that list may grow. Instead of MkDocs trying to manage some allowlist, I'm not sure that a plugin is such a bad idea to add whatever folders you feel are important. That is, of course, my personal opinion 🤷.

[pxeger]

I just think it seems such a basic functionality that it should be configurable without writing a custom plugin, in mkdocs.yml (or, ideally, by not configuring at all, it is just the default)

[facelessuser]

I guess it boils down to the maintenance cost. MkDocs provides basic functionality and pushes off the rest to plugins to probably drive maintenance costs down. Mildly inconvenient to some users, but helps distribute the workload.

I'm sure a lot of features could be argued to be more helpful to just include, but someone has to implement and maintain it, so lines have to be drawn somewhere. This may be one of those lines.

With all of that said, I'm not the current maintainer, and this decision isn't mine to make, and frankly, I don't know who the current active maintainer is as I feel like our recent maintainers may have gotten burned out.

[wsmckenz]

So, in mkdocs, the exclusion list is simply an array of .gitignore style exclusions. It's seems pretty trivial to replace that with a .mkdocsignore file if such a file exists. I'd be happy to do the PR, but I think for @waylan the issue is more how much complexity you want to add to the base product. I got around this by adding an on_files event that added back in the directory that was skipped.

[facelessuser]

I'd be happy to do the PR, but I think for @waylan the issue is more how much complexity you want to add to the base product. I got around this by adding an on_files event that added back in the directory that was skipped.

This is exactly what I think the point is. It's not hard to for people to augment, and by pushing it off to plugins, you keep the base simpler and easier to maintain. For a lot of people, the base functionality is fine, for those who need more, there are plugins.

[pxeger]

the issue is more how much complexity you want to add to the base product

But ignoring certain files is a complexity that could be removed. I still can't honestly see why one would put any files in their docs folder unless they wanted them included in the output, so this whole exclusion system seems pointless to me. (Happy to be proven wrong, of course, if anyone has a use case)

[waylan]

But ignoring certain files is a complexity that could be removed. I still can't honestly see why one would put any files in their docs folder unless they wanted them included in the output, so this whole exclusion system seems pointless to me. (Happy to be proven wrong, of course, if anyone has a use case)

I agree, but search the closed issues here and you will find all sorts of arguments for why people think that various alternate behaviors are a good idea and should be the normal expected behavior. In fact, this is the first request I recall asking us to ignore less files. All the previous requests have asked us to ignore more files. Which only proves the point that it is impossible to meet everyone's expectations. Therefore, we provide a base and allow others to customize it through plugins. That base happens to fit the needs of the core devs (personally, I have never needed any third party plugin). But then, we did the work.

So if you want a feature, you can do the work. Right now I have taken a step back from working on McDocs. Any additions would just create more maintenance, which I don't have time for. However, we have a Plugin API for just this reason.

[tannersullie]

I have this issue as well. I use Azure DevOps to manage my .md documentation. My folder structure looks like this:

• Documentation (repo)
  • APP1
    • Topic 1 Folder
      • Page01.md
    • .assets
      • .image
        • .img-pg-name
          • IMG1.png
          • IMG2.png
          • etc.
        • .img-pg-name
          • IMG3.png
          • IMG4.png
          • etc.
    • Overview.md
    • Topic-1.md
  • APP2 ...

I use reference-style links as well, but based on what I read, that doesn't seem to be an issue. e.g., ![alt-txt][ref1] (towards the end of the .md doc >) [ref1]: <.assets/.image/.overview/img.png>

Is there a recommended add-on to work around this?

[4ch1m]

Is there a recommended add-on to work around this?

Not sure if this helps with your folder-structure, but I'm using the awesome gen-files plugin to create "hidden files" (alongside the standard build-phase).

[fs-xx]

In fact, this is the first request I recall asking us to ignore less files. All the previous requests have asked us to ignore more files.

I love that it works like this. I was looking for a way to exclude drafts from the current build without having to keep them in a separate project folder and adding . to the filename does exactly what I need, super simple. (Thank you for mkdocs, it's pretty great!)

[oprypin]

For reference, the code responsible for excluding dot files is here https://github.com/mkdocs/mkdocs/blob/62e312478efe4f17a62d7fd280e5863aa9635a62/mkdocs/structure/files.py#L282

[oprypin]

The way I'm thinking to tackle this is by adding a new config.

exclude_files: |
  .*
  /templates

And I'm thinking the above will be not merely the default, but rather the always implicitly prepended value. And so the way to once again include .well-known would perhaps be...

exclude_files: |
  !.well-known

Then we veer off to the path of parsing a gitignore-like spec. Which would be great, except for the part of finding an implementation that is not buggy, outdated, overengineered, etc.

It's also tempting to name this ignore_files for the familiarity, but there might be 2 separate concepts of ignoring files in different ways - the other one would be to ignore files just for the sake of the nav inclusion warning:

• #1888

[oprypin]

Looking towards https://github.com/cpburnz/python-pathspec :eyes:

[fs-xx]

The way I'm thinking to tackle this is by adding a new config.

exclude_files: |
  .*
  /templates

And I'm thinking the above will be not merely the default, but rather the always implicitly prepended value. And so the way to once again include .well-known would perhaps be...

exclude_files: |
  !.well-known

This would conform to what behaviour I expect (hidden files wouldn't build by default) and seems like it would be simple and flexible to change, at least on the user side. Hopefully for you too! :sweat_smile:

[th0mk]

For anyone who might also have searched how to include the .well-known directory with mkdocs, this is now possible thanks to the above pull request with a new config option.

Just add the following to your mkdocs.yml:

exclude_docs: |
  !.well-known