Replies: 4 comments 27 replies
This comment has been hidden.
This comment has been hidden.
-
I think we should discuss if we want to move away from |
Beta Was this translation helpful? Give feedback.
-
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 |
Beta Was this translation helpful? Give feedback.
-
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. |
Beta Was this translation helpful? Give feedback.
-
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.
Beta Was this translation helpful? Give feedback.
All reactions