Hi! I went looking for answers about Markdown as well... Shortly after
finding no answer here, I discovered what I needed myself with a custom
theme and the html_file_suffix option for your conf.py file.
Now, this won't turn the actual markup into Markdown. But like Roberto
said, HTML is valid, so I just wanted the files to come out with the .md
suffix so I don't need another script to change the filenames. But I also
wanted to strip down the output to only the bare minimum body copy (no
header, nav, footer, etc.) so that I can put these pages into an existing
website structure.
So for posterity, here is my solution...
First I added the following to my conf.py:
html_theme = "coral_theme"
html_theme_path = ["."]
html_file_suffix = ".md"
My custom theme (in a directory named "coral_theme", in the same directory
as the conf.py) is very simple...
theme.conf:
[theme]
inherit = basic
layout.html:
{% block body %}{% endblock %}
search.html:
{{ toctree() }}
That is it!
Wait, what's going on with search.html? Well, I don't actually need a
search page, because like I said, I'm putting all this into an existing
site. So I'm simply repurposing this file as the output for stand-alone
links for the generated pages. So the search.md output is just a <UL> list
of all the generated docs. Then I can just plop that HTML into my website
nav and I'm good to go. (This way, I didn't need to bother updating the
actual Builder to output a new file type... and I didn't see any other way
to do that.)
So there it is: Perhaps the most simple custom theme plus the
html_file_suffix config, and you have raw "markdown" files with none of the
other fluff.
I hope this helps somebody else. :)
On Wednesday, October 24, 2018 at 2:34:16 PM UTC-7, Erin Kelly wrote:
>
> So, I was happily using Sphinx and then my company got acquired, and now
> all my documentation has to be published in GitHub Markdown format.
>
> I am already going crazy trying to maintain the simplest document header
> cross-references by hand, and my fingers ache from having to type my
> camel-case, hyphenated product name over and over and over ...
>
> I know there isn't a .md output option, but how hard would it be to create
> one? Has anyone tried or asked about it?
>
> Just hoping....
>
--
You received this message because you are subscribed to the Google Groups
"sphinx-users" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
To post to this group, send email to [email protected].
Visit this group at https://groups.google.com/group/sphinx-users.
For more options, visit https://groups.google.com/d/optout.
