Better deploy guide page

[Andre601]

This was mentioned in the mkdocs repository itself but has gone under unfortunately, which is why I now raise it here for a hopefully constructive discussion.

The current guide on deploying your docs is recommending methods one may not consider to be optimal anymore.

As an example, the section for GitHub pages is still recommending to utilize the gh-deploy command, while usage of GitHub Actions is a much more favourible aproach due to its higher customization capabilities compared to the more rigit command itself.

So the docs could be improved there to include the GitHub Actions aproach as a recommended way. And perhaps could it be further expanded to include other CI/CD tools such as Woodpecker-CI to further help in automating documentation deployment for ones project.

[squidfunk]

I think we should discuss if we want to move away from gh-deploy, as there are so many more options to deploy a documentation site right now. It would also mean we could reduce the API surface and close many issues that ask for additional flags or functionality for gh-deploy (e.g. dry run or commit signing) as out of scope. Also, deployment just involves copying static assets, so I agree that a deploy guide with the most common deployment targets is a great idea to have in the docs!

[squidfunk]

Subcommand support (as git supports it) would be awesome, maybe something to consider for the future Edit: @waylan do you have any resources talking about subcommand support? Is it hard to implement? If we could implement it without too much hastle, I'd be up for moving that up the priority list, as it will give us another very powerful degree of freedom.

But I am open to some sort of mkdocs-deploy plugin that could allow one to deploy to more than just Github.

Fully agree. Implementing deployment as part of a plugin is trivial – all can be done in on_post_build. Thus, I'd say we should deprecate gh-deploy, and either move the logic into a subcommand (if we could support to register those easily) or into a plugin, and remove it in the next major release. Modularizing deployment would also allow platforms to provide custom implementations that integrate with MkDocs. Additionally, we would unopinionate MkDocs by untying it from GitHub.

The deploy command also gives new users a great way to try things out and get something live. I agree it doesn't grow well for more advanced users (which we would all be) but let's not forget keeping the simplest and easiest on-ramp for newer users.

I also agree that we should be very concerned about the DX, especially for new users.

For a bit of history... back when the plugin API was first introduced the intention was to add the ability for plugins to add their own subcommands to the mkdocs command. The first subcommand which would be the test of the implementation would be a new deploy command which would accept third-party subcommands for various services and/or deployment scenarios. Obviously, none of that ever happened. It kept getting pushed back by more pressing matters and then users had already developed their own standalone solutions. When we reconsidered, the conclusion was that the scope of MkDocs had been refined and it no longer was in-scope to provide those utilities inhouse. Of course, the existing tool remained to maintain backward compatibility for all of the users who were already using it.

Today, project scope is back up for discussion. Personally, I am fine with going either way so long as I'm not the one maintaining it. As a past maintainer, I will observe that keeping the scope small is less of a load. Regardless, if the decision is to remove the existing command, I only ask that we have a long and slow deprecation with warnings across multiple releases.

Fully agree. Regarding the deprecation path: yes, we need one, but IMHO, we also need to make releases smaller and release more often. The last release is 7 months ago and merged changes are piling up.

[mkusz]

@squidfunk I need to take a deeper look into source code of commands in MkDocs, but I had created some plugin mechanism in the past in click, so I don't think it will be difficult. It's just a matter of some design decisions how we want to handle by external plugins (per plugin namespaces?).

PS. You can find an example of plugin mechanism inside my set of plugins here. It shouldn't be hard to use the same mechanism in MkDocs core.

[waylan]

@mkusz is correct. We are using click for commands and it is relatively easy to support plugins with that lib. The question is how we want to make them available. For example, should commands from all installed plugins be available or only commands from plugins enabled in a projects' config file? And what happens when 2 or more plugins provide a subcommand with the same name? Work those details out and the implementation is pretty simple. We just need a mechanism for a plugin to indicate it has subcommands and tell click about them. So long as the plugin provides a valid click command it should work.

[mkusz]

@waylan one of the options is to create namespaces and use something like mkdosc myplugin mycommand but we should also have an ability to override myplugin name inside of the plugin config. Probably this config key should be something like _plugin_name = "myplugin" (this will follow the PEP8 naming convention meaning "be aware what you are doing with this parameter"). This mechanism should be also used to override plugin name used in config (not sure if this is possible, but this is Python). This kind of mechanism can also solve some potential problems with plugins names conflicts.

As for what methods are available, I think that we should have 2 possibilities:

• default behaviour - commands only from enabled plugins
• forced - commands available always (probably some decorator will be the best option here)
  The main idea for forced commands should be to use them, only for some actions related to plugin setup like enable plugin, change settings, install additional tools, etc. If we will restrict it to only installed one, some plugin creators will fall back to into current state and make their own CLI tools.

In general, I'm huge proponent of giving plugin creator options (with recommendations), not restrictions.

[unverbuggt]

I think implementing something like "mkdocs myplugin plugincommand [args]" would be really useful. This way different deploy plugins could be used or other jobs like indexing or caching could be automated (and not simply run on all build/serve).

[Andre601]

I quickly want to mention that I've created a discussion for collecting setups for common CI/CD systems to automatically deploy to Static site hosts.

Additions to it would be greatly apreciated! #3652

[waylan]

So the docs could be improved there to include the GitHub Actions aproach as a recommended way. And perhaps could it be further expanded to include other CI/CD tools such as Woodpecker-CI to further help in automating documentation deployment for ones project.

I haven't addressed this specifically yet and it is bothering me. The general approach I took in the past when documenting deployment is not to document each individual site/tool. but to provide general information which could be applied across all sites/tools. So, for example, if a task can be completed with a series of command-line commands, then document those commands. Each individual CI service has its own way to configure the same series of commands and the specifics of how to define dependencies and the commands varies from service to service. But the basic commands are often the same. Therefore, all we need is to provide a general list of the dependencies and the series of commands and that should be enough for all CI services.

For example, consider the existing documentation about deploying to GitHub Pages. Personally, I find that documentation helpful even when using GitHub actions to deploy to GitHub Pages. Specifically, it outlines the differences in deploying to an org/user Pages site versus a project Pages site. Understanding that difference is important to properly configuring the action for my specific repo. True, the docs don't give me the actual action config, but they do give me the information I need to configure my own action config (like I did here).

That said, users often are not experts on the subtleties of the specific config file format a service uses and don't know about various obscure config options available on that service (and aren't likely to know or use the right search terms to find them). And even if they are, a user may not be a posix expert and won't necessarily know the ins and outs of making the same series of commands work on slightly different systems. Therefore, there is still value in having example configs for the various CI services out there. However, those services are often a moving target as they update and change their systems. Yet, MkDocs' documentation is generally updated on MkDocs' release schedule, which causes delays in getting deployment documentation updated in a timely manner.

Therefore, my suggestion would be to perhaps have a series of wiki pages for documenting example configs for various CI services. The official documentation can contain the basics that applies to all services and then point to the collection of wiki pages. In that way, anyone can update the relevant information for a specific service immediately and not be dependent on MkDocs' release cycle.

[Andre601]

I feel like another point could be what I have right now, which is a discussion acting as a collection of available CI/CD setups.

Also, one thing worth noting regarding GitHub Actions: If the deployment is done directly in the action (As in not pushing to the gh-pages branch like the gh-deploy command does) are you required to define the custom domain in the pages repository settings, not in a CNAME file...
If a wiki page would be made, which I personally would consider somewhat disconnecting here from the docs themself, should this key-aspect be pointed out.

[pawamoy]

If the release cycle is an issue for up-to-date docs, then we can speed up the cycle (release more often, smaller sets of changes), and/or host docs for both stable and development versions. Docs for the development version would be updated after each merge, and docs for the stable version would be updated upon release.

[waylan]

are you required to define the custom domain in the pages repository settings, not in a CNAME file...

The depends. Previously GitHub only provided the CNAME option. The config setting was a latter addition. When building a custom tool, having the tool insert the CNAME file is a convivence for the new user and it removes the need for the user to be concerned about it. However, when documenting generic git commands, having to also document creating a script to insert a file is complicated. In that case, documenting use of the repo setting might make more sense. The thing is, if GitHub deployment was documented on a page by itself, all of the above could be covered in various subsections.

If a wiki page would be made, which I personally would consider somewhat disconnecting here from the docs themself,

Yes, they should be disconnected, which disconnects them from the release cycle for updates. Imagine the scenario where a service updates their system the day after MkDocs does a major update. It may be months before MkDocs documentation will receive an update, even if a PR is pushed immediately. By having a separate publicly editable page, it can be updated immediately without involving the core team. It could be that no one on the core team is even familiar with that particular service. They may not feel comfortable reviewing any proposed changes. Therefore, it makes more sense for the page for each service to be updated and maintained by someone who uses that particular service and is following that service's updates and changes. And that means it should be outside the primary documentation.

Whether that location is some pinned discussions or wiki pages, doesn't really matter, so long as it is a known, easy to find location. Discussions retain the history and discussions around the current method, but the the currently relevant info is not always at the top. Whereas a wiki page is edited so that only the current info is displayed and discussions and changes are disjointed. But then, some systems have been know to mix those two approaches to varying degrees. Each approach has its own strengths and weaknesses. My point is that I think this doesn't belong in the primary documentation. Where it goes instead depends on which set of tradeoffs the community wants.

[Andre601]

I feel like the docs shouldn't be split up into mkdocs and a separate wiki. It just feels wrong. Because at that point could we also just sent them to StackOverflow or GitHub Discussion replies for pretty much the same effect.

I like the aproach of the docs for different versions (One for release, one for latest commit) and this could be achieved using Mike. Tho, it would require modifications of (at the very least) the docs themself to override the template and inject the necessary stuff here.

The benefit would be, that we could have a documentation based on latest commit, while also having one based on latest releases, allowing a user to see info for what is to come and what is already available.

[Andre601]

To add to this. Various other pages often provide a similar system where they have the docs available for release versions and development versions.

To give some primary examples:

• GitHub Documentation
• Woodpecker-CI
• Docosaurus

It feels like a good idea to have versioned docs available, not just for faster docs updates, but also for preserving past iterations.