[FEAT]: Add `awesome-pages` into the Docker image

• I’ve read the contribution guidelines and agree with them

I want to suggest an idea and checked that …

• … to my best knowledge, my idea wouldn’t break something for other users
• … the documentation does not mention anything about my idea
• … there are no open or closed issues that are related to my idea

Description

Would it be possible to consider adding back the awesome-pages plugin?

This was deprecated back in 5.5 and removed in 6.0 with the reasoning of size concerns. While this is valid with mkdocs-git-revision-date-localized-plugin (31MB layer), mkdocs-awesome-pages-plugin only adds 323KB as layer weight.

Justification

If size is a concern, it looks like there is plenty of opportunity to reduce the Docker image further.

• For example the lunr package includes a 4 rust_stemmer.cpython.*.so files, 3 appear to be diffentiated by 35m, 36m and 37m… which I assume might be relevant to Python version support? These are files built during install not source files, they have a weight of 2.7MB each, two can be discarded and the container would work as intended still. Furthermore the 4th file is a binary for darwin (macOS), 345KB right there that could be swapped out for awesome-page.
• nltk which seems to be a supporting package for lunr I think is a 9MB package, there’s 1.2MB test directory that I doubt is required for this project?
• python3.8 in total is 52MB, with site-packages at 48MB, I don’t know Python well enough to know if anything else could be cleaned up from there.
• git and related dependencies also eat up around 20MB in size (this layer is 77MB). Technically a slimmer image could be used if a minimal/slim base image was useful for most users (serve and possibly build?), those that would use the image to deploy could use a deploy variant, but I imagine most would be fine deploying the build output via other means.
• The earlier layers from the python image you extend is about 40MB in addition to all this. Total image size is 126MB.

These insights were provided via the CLI tool dive. The alternative git revision date plugin mkdocs-git-revision-date-plugin weighs 1.3MB btw if you were interested.

Use Cases

Considering it’s usefulness for some, this seems useful to include by default vs requiring a separate Dockerfile being maintained by projects (as this one is rather popular AFAIK when it comes to choosing MkDocs).

At less than 0.3% increase in size, I think this is perfectly valid to consider for the added flexibility in adopting MkDocs when migrating from another docs platform. A project can refine it’s nav over time this way.

There’s a related feature request for upstream MkDocs (since 2015) as MkDocs only offers explicit or implicit sidebar/nav without that linked extension. In that feature request, the OP is referencing GlusterFS docs which involved a 200 line config for nav where sometimes it’d be nice to just explicitly declare top-level categories and then glob the directory files and any nested children.

[squidfunk]

To sum up: you are free to build your own Docker image variants from the given Dockerfile! If you do, we can link to them from the official documentation as an alternative for when you don’t want to roll your own!

[squidfunk]

They very much don’t want to maintain their own Dockerfile and keep that image in sync with yours, they don’t want to impose an additional build step on contributors, and they’d rather use your image which has higher trust than a third-party one if they’re not maintaining the slight modification to add a small plugin.

I understand the trust issue, but in the end the maintenance necessary for this plugin would be deducted from my time from this project. I try to keep dependencies at a minimum, which is why I’ve thrown out Webpack in favor of a completely custom build process (~500 dependencies less to worry about).

In the meantime you do have the option of trimming the fat I pointed out if you want to reduce file size. That’s a free 7MB reduction by adding an extra line to the RUN command, which is the bulk of the lunr package.

I’m very interested to collaborate on a PR to reduce the fat. As you might have seen, I’m also removing the regular MkDocs themes, because they carry web fonts of 10MB. Removing anything else unnecessary is much appreciated. However, all existing functionality should be kept.

I’m not sure how you plan to approach this in future if search was made optional though, defer users to also extend the image to add the search plugin themselves?

Search is an integral feature of Material for MkDocs. I have no plan to remove it from the Docker image.

Do you happen to know how your users are deploying usually? If they’re using gh-deploy for example which is what I’ve seen usually advised for MkDocs deployment, it’s often because that’s what the docs or articles advise the user to do. Github Actions workflow is pretty simple for handling deployment, as is hosting the build output on a VPS or Vercel/Netlify.

If we remove it, it will break a lot of pipelines with the necessity for adaption. I have no interest managing the issues rolling in.

22MB? For that 77MB layer in your image? 20MB-ish is for git, 52MB for Python related files (just this layer, excludes pip and base python from the image you extend from). You’re removing 30MB? (assuming those dependencies aren’t required by anything else and can be removed)

The 22 MB was concerning MkDocs + dependencies, not the whole image.