Conversation
|
Hey, thanks for raising this PR. This doesn't completely solve the related issue though; that states that the cookiecutter template should give the option for mkdocs or zensical, and allow the generated project to work with either. |
|
Yes, I did not touch the template yet, since I wanted to discuss the changes to the visuals first before investing into changes of the template itself. Currently, the changes only affect the project documentation. If you are fine with the current changes I am happy to complete the job for the template. |
Ah I see! Yes, I would be open for this. Coincidentally, I wrote a blog post about the current state of MkDocs a few days ago. Moving the docs four the project itself to Zensical is fine for me. I think the best solution for the template (for now) would be to support both MkDocs and Zensical, and provide the user the option to choose. Ideally we add a unit test for both options that verifies that the Is this something you are willing to work on? If so, that'd be great. I'm happy to help with testing of course. |
yes, I am down. I start working the changes into the template. |
|
There seem to be a few merge conflicts. |
|
I tried to run it locally, by running Seems like there is still a small issue somewhere. |
while evaluating the current design and options mkdocs still stays present.
The config is stripped from generated comments The config is mostly the default except the project entries nav is also transfered from mkdocs.yml aswell as extra_css. Additional a few features are enabled which were not present in mkdocs.yml: ### Edit Pages `edit_uri` was set in `mkdocs.yml` but features were not activated. The Features are now activated ### Markdown Extensions They don't need to be present on Zensical they are builtin. ### Theme Pallete Migrated to toml format ### Extra Social Migrated to toml format ### Fonts I left the fonts uncommented/default. The fonts changed from mkdocs to Zensical but where not configured in mkdocs
The default fontsize is a bit larger than on mkdocs. For me the old size matched better the nav.
previous the header bg was quite dark. with mkdocs this was not an issue, because the colors where differently distributed. I tried to achieve similiar with the light theme in zensical, but every change effected some other element. So I decided to brighten the header background, so that the header fg is still readable without effecting the rest of the theme.
- precise the gitignore - use zensical in Makefile - replace mkdocs with zensical as dependencies
THIS COMMIT is not tested! - replace mkdocs for zensical - replace branch pages with pages-artifacts The second is necessary and best practice since zensical does not support gh-deploy like mkdocs: https://zensical.org/compatibility/cli/
- update docs_tool parameter - Extend tests to test for the different config files New Test: - test_zensical
MaKaNu
force-pushed
the
87-add-support-for-using-zensical
branch
from
42a2cba to
7cac290
Compare
Ah, I somehow missed that quotes as I transferred from yaml to toml in the upper half of the Additional added a validity test for the zensical.toml inside the template. Merge Conflict solved by applying the update dependencies. |
2 participants
PR Checklist
docsis updatedDescription of changes
I tried to experiment with zensical implementation.
While reading through their docs and migrating the old config, I realized a few nice things they used/implemented wit zensical.
The main goal of this PR is to recreate the current mkdocs setup with zensical.
While the changes with the logos and icons on the nav section are optional, the color scheme changes seem to be necessary, since a few quirks in the old mkdocs material have changed drastically (see de5e52a) correcting those would mean more drastic changes in the
extras.cssTODOS
Effects for users:
Fixes #87