search

jgrassler / mkdocs-pandoc

[unmaintained] mkdocs -> pandoc converter: use this fork https://github.com/twardoch/mkdocs-combine
Apache License 2.0
107 stars 39 forks source link

generated headings might need extra line breaks or indenting fixed? #8

Closed mkoertgen closed 8 years ago

mkoertgen commented 8 years ago

As mentioned in https://github.com/jgrassler/mkdocs-pandoc/issues/5#issuecomment-173835953 the generated output might need unexpected extra line breaks.

To reproduce this have a look at mkoertgen/mkdocs-pandoc-samples. The ./headings directory contains a sample project that reproduces this issue - at least on Windows.

I used

mkdocs2pandoc -o mydocs.pd
pandoc --toc -f markdown+grid_tables+table_captions -o mydocs.pdf mydocs.pd

Here is the relevant section in the generated .pd

#### Another Heading 2

Lorem ipsum...
## Say B

### Say B (Heading 1)

For me the generated mydocs.pd looks ok but maybe the pd-syntax requires empty lines between headings. So maybe it's pandoc that requires an extra line here.

Finally, the generated mydocs.pdf includes some lines ending with the extra headings generated by mkdocs2pandoc (cf. attachments)

As a workaround i started adding html page breaks (at the end of overview/a.md)

<div style="page-break-after: always;"></div>

After that i realized that adding an extra line break at the end of the files also works around this issue.

jgrassler commented 8 years ago

That's exhaustive, thanks! I'll try to reproduce this on Linux and/or check the documentation I use for testing (https://github.com/autostrap/autostrap-docs.git) for an accidental occurence of the workaround you mentioned.

jgrassler commented 8 years ago

Bug confirmed: it affects Linux as well, and it's not related to CRLF line terminators (converting the files to unix style newline-only line causes the same breakage. I'll try to make some time to fix it tomorrow.

mkoertgen commented 8 years ago

Great, thx.

jgrassler commented 8 years ago

Fixed in branch issues/8. Tested fine on Linux with Python 2.7 and Python 3. Can you check if everything works on Windows as well?

If so I'll merge it and cut a new release.

mkoertgen commented 8 years ago

Looks good. Tested on Windows with Python 3.4, pandoc 1.16, pdflatex (miktex 2.9).

btw, maybe some hints for Windows installation would be a good fit for the readme. Chocolatey has become quite popular. You would need

choco install python
choco install pandocpdf
jgrassler commented 8 years ago

Happy to hear it works. Merged.

Before I cut the official we-now-support-Windows release let me get the installation procedure for Windows/Chocolatey straight:

choco install python
choco install pandocpdf
pip install mkdocs-pandoc

is that all it takes? Apart from installing Chocolatey itself, that is. I consider that bit well out of scope and will just put a link to Chocolatey in there.

mkoertgen commented 8 years ago

Yup, that's all it takes. Typically you would additionally install mkdocs as well

pip install mkdocs

but for mkdocs-pandoc that's all.

jgrassler commented 8 years ago

Ok, thanks. Then I'll add that to the README.md, minus the mkdocs part, that is. Technically it's not needed but since I wasn't too sure initially, I added it to the package dependencies back when I wrote mkdocs-pandoc. As you pointed out, it makes sense to have it around so I'll continue to keep it in there :-)