Switch to MKDocs #602
Switch to MKDocs #602
Conversation
This is a work in progress. I merged in 6f87b32 from the md3 branch. That branch has all of the extension docs removed, so they haven't been converted yet. And I only resolved conflicts and updated mkdocs.yml to the current MkDocs format. Addresses Python-Markdown#601.
Assumes a git remote is set up named "pages". Do
git remote add pages https://github.com/Python-Markdown/Python-Markdown.github.io.git
... before running `make deploy` the first time.
|
I still need to do an audit of the docs to make sure I didn't miss anything, but I pushed the deployment up to GitHub Pages. However, weirdly the homepage is not showing unless I include |
|
https://python-markdown.github.io/ works for me |
|
Just my 2 cents, but links are hard to see in that theme. If you can make them stand out a little, it might help with navigation. |
|
The homepage works for me from a different location/machine. Must have been a caching thing causing the problem.
The CSS is completely unmodified from the Sphinx theme. That is the "problem" with navigation? I didn't have any problems, but then I'm intimately aware of the structure of the theme. I did notice that tables seem to be completely unstyled, so that may need to be investigated and possibly addressed. But that would likely happen upstream on the theme, not here. Regardless, at this point I'm mostly concerned with the MkDocs config, whether all internal links are properly converted, and if the rendered Markdown works with the theme (for example, some code blocks might need to have a language identified as language guessing appears to be getting it wrong). I'll be doing an audit page-by-page, so if anyone sees anything, let me know in a comment and I'll be sure to address it. |
Dark navy blue and black is hard to distinguish...at least for me (at first). I had to mouse around to get the link to turn red on hover to see where they were. Once I stared at it a bit, I more easily noticed the subtle differences, but I'd argue they are a bit too subtle. It won't really affect me much as I don't often have to reference the docs, just my general impression. Lightening it up to It's up to you, just figured I'd mention it, I'll deal regardless. After a bit my eyes can see the difference. I just personally dislike sites where clickable things are too subtle (this happens a lot with the flat theme trend). I feel like I just flail my mouse around until I see the cursor or the link change to some easy to see hover state. |
|
After a lot of cleanup, I merged this. We can deal with theme related issues separately. |
| @@ -22,6 +22,7 @@ install: | |||
| deploy: | |||
| python setup.py sdist --manifest-only | |||
| python setup.py sdist --formats zip,gztar upload | |||
| mkdocs gh-deploy -r pages -b master | |||
There was a problem hiding this comment.
Turns out this doesn't work. It hoses your local master branch the first time and then (after more commits are added) results in merge conflicts. See c-w/ghp-import#65 for details.
This is a work in progress.
I merged in 6f87b32 from the md3 branch. That branch has all of the
extension docs removed, so they haven't been converted yet. And I
only resolved conflicts and updated mkdocs.yml to the current MkDocs
format.
Addresses #601.