Replies: 1 comment 6 replies
-
|
Thank you for providing this post. This was really helpful and important since GH has added these actions for handling docs. However, one curiousity I have is, how do you deal with versioned docs with this setup? This seems to be really difficult to find information for using mike and these new GHA. Instead of doing |
Beta Was this translation helpful? Give feedback.
-
|
Honestly, this sounds more like a Mike issue and something that should be worked. Hardcoding your software on a specific branch - even if configurable - is a very limiting factor, and I'm sure there are other aproaches that could work. |
Beta Was this translation helpful? Give feedback.
-
|
This is absolutely a |
Beta Was this translation helpful? Give feedback.
-
|
@whompyjaw you could instead use readthedocs to publish your documentation; they provide full versioning for your documentation without the need to push to a branch. There is a example repository to help you get started. |
Beta Was this translation helpful? Give feedback.
-
|
Hello, I wrote in another discussion that |
Beta Was this translation helpful? Give feedback.
-
Yes, it is a wrapper, but only insofar that it'll use mkdocs to build the 'current' documentation version in a subdirectory, update its own metadata and any version links, then commit the changes to the gh-pages branch. It can also manage the other versions (including deleting them), and maintain aliases via commits. It is the metadata (version info, links) and already built older versions that are the crucial part here. If this data could be stored elsewhere or be maintained as part of a normal release process you'd be golden. But retooling For |
Beta Was this translation helpful? Give feedback.
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
-
This is some small feedback on the GitHub Actions section in the "Publishing your site" page, which while already fairly good, could perhaps receive some smaller improvements.
Overall are there only 3 things I would like to address here.
The first one is the first step:
This setup has the issue, that a fetch-depth of 1 is used by default, meaning only a shallow fetch is being performed.
This can cause problems if a user is using MkDocs plugins that utilize git to fetch information (Commit history). A prime example would be the git-localized-revision-date plugin, which would print warnings about inaccurate commit history.
It should be addressed (possibly in an annotation) that this problem could be caused and that a fix would be to apply a fetch-depth of 0:
The second point is on the step right afterwards:
This step is for the most part not necessary. The checkout action should've set up the git configuration already and most if not all actions required don't need a user setup. I assume this step is needed due to the reliance on the
gh-deploycommand of MkDocs?If that is the case, then the next point would be a recommended change to consider for sure.
The final point is to not recommend the usage of
mkdocs gh-deployin GitHub Actions, especially given that it is mentioned later on anyways as its own section.Instead, a direct deployment to GitHub Pages should be done here. This, however, would require some multiple adjustments to the example file like this (less condensed for better readability):
This setup would bring several benefits to the user:
This actions setup, while a bit bigger, would offer a better use of GitHub Actions.
I hope the changes can be considered.
Beta Was this translation helpful? Give feedback.
All reactions