Collect images from a directory tree and add them to a markdown file.
Project description
imdown
imdown (pronounce "I'm down") can be used to collect images from a directory tree and put them into a markdown file for markdown to compile to another format using pandoc (although I typically use pdf's so its targeted at that mainly.)
install
Install from PyPI:
pip install imdown
or from GitHub:
pip install git+https://github.com/LeSasse/imdown.git
Write new files
Try out the example
You can try it out on the example provided in this repository. Go to the example
directory:
git clone https://github.com/LeSasse/imdown.git
cd imdown/example
Collect all images from the figures directory and put them into a markdown file:
imdown figures -o markdown_files/all_filetypes.md
and see the result in markdown_files/all_filetypes.md. Or filter out a specific filetype only i.e. pdf's:
imdown figures -f pdf -o markdown_files/only_pdfs.md
You can then manually adjust the markdown file and compile via pandoc. If you do not need to adjust it and just want the pdf, you can also skip the intermediate markdown file and pipe it straight into pandoc (of course for this you need pandoc installed!):
imdown figures -f pdf | pandoc -o output_pdfs/piped.pdf
and see the result in output_pdfs/piped.pdf.
Adjust the paths written in the markdown output
By default imdown will write all the paths relative to the directory
in which the markdown file will be written (or from current directory if the
markdown is just printed to stdout). However, you may not always like to build
your final output format from the same directory as the markdown file, so you
can specifiy -b, --build_directory, so that all paths will be written relative
from this directory:
imdown figures -b . -o markdown_files/build_directory_specified.md
Check the result in markdown_files/build_directory_specified.md
and you can see that the paths are relative not from the md file but from the
directory you specified (i.e. the current directory). Note that of course the
example in the repository is therefore not able to show the pictures in that
particular md file. Alternatively, you can also simply use the -a, --absolute
flag to write all paths as absolute paths.
Ignore paths or filenames based on a string
You can pass a string to the -i, --ignore flag. If any of the paths/filenames
of the images include this string, it will be ignored.
For example:
imdown figures -i analysis1
will result in:
You can also ignore multiple strings, i.e.
imdown figures -f pdf png -i analysis1 analysis2
will result in:
Walk only to a certain depth
You can specify how many levels the program should walk the directory tree. If None (default) the program will walk all the way. Specify 0 to only consider files in the initial directory. For each level deeper add +1. For example:
imdown figures -f pdf png -d 0
will output nothing, as there are no files in the initial directory. However, specifiying one level will be enough to give the same output as the default in this case, as the program will go one level deeper (but there are no levels beyond this in the example).
imdown figures -f pdf png -d 1
Update manually adjusted markdowns
Now imagine that you manually adjusted captions or text in one of the markdown files. But you also added new plots to your directory and want to add them to you markdown or you want to include filetypes that you did not include previously.
For example consider markdown_files/manually_adjusted.md. This is the markdown that I created only using pdf plots. I now also want to add all png's. I have adjusted the captions and added some text and of course I do not want to lose that text when adding new plots. In order to do this I can provide the adjusted file as a reference file as an additional argument and add only the new plots. For example I can test it and print the updated version to stdout:
imdown figures -f pdf png -r markdown_files/manually_adjusted.md
which should output:
I have also added some text.
Note that this outputs all paths as relative to the current directory, since you are printing to stdout. The advantage is that the old paths aren't just valid from the reference file, but you can also write it to a new file, in which case paths will be written relative from that file:
imdown figures -f pdf png -o markdown_files/manually_adjusted_and_updated.md -r markdown_files/manually_adjusted.md
for which you can find the result in markdown_files/manually_adjusted_and_updated.md.
Of course you can also overwrite the reference file, but do that at your own risk. Another advantage of this is, that you can take the reference file, update it with the new plots, and pipe it straight into pandoc again, if you like:
imdown figures -f pdf png -r markdown_files/manually_adjusted.md | pandoc -o output_pdfs/piped_from_reference.pdf
You can see the result at output_pdfs/piped_from_reference.pdf
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for imdown-0.0.1.dev13-py3-none-any.whl
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 7721f89ea45fd9a6ab6197d0d5ca4331ef88539279b02881504f8eeb43e3e841 |
|
| MD5 | 989b5d0676a7062433e448013a706f1a |
|
| BLAKE2b-256 | 7c3b1d0d8d82151c51d2497dd109ff652833d524a0ccc5e27595a9adc858a4a8 |
