| Name | imdown JSON |
| Version |
0.0.1.dev13
JSON |
| download |
| home_page | |
| Summary | Collect images from a directory tree and add them to a markdown file. |
| upload_time | 2023-11-12 14:49:24 |
| maintainer | |
| docs_url | None |
| author | Leonard Sasse |
| requires_python | >=3.7 |
| license | |
| keywords |
pandoc
markdown
images
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# 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](https://pandoc.org/)
(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](example/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](https://pandoc.org/).
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](https://pandoc.org/) installed!):
```
imdown figures -f pdf | pandoc -o output_pdfs/piped.pdf
```
and see the result in [output_pdfs/piped.pdf](example/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](example/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](example/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:
```markdown
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](example/markdown_files/manually_adjusted_and_updated).
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](example/output_pdfs/piped_from_reference.pdf)
Raw data
{
"_id": null,
"home_page": "",
"name": "imdown",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "pandoc,markdown,images",
"author": "Leonard Sasse",
"author_email": "l.sasse@fz-juelich.de",
"download_url": "https://files.pythonhosted.org/packages/6b/f7/469e013b2fbe2b8ff0dd248e0561ee8d4d1fbd7a221c943699d3e3da0f9f/imdown-0.0.1.dev13.tar.gz",
"platform": null,
"description": "# imdown\n\nimdown (pronounce \"I'm down\") can be used to collect images from a directory\ntree and put them into a markdown file for markdown to compile to another format\nusing [pandoc](https://pandoc.org/)\n(although I typically use pdf's so its targeted at that mainly.)\n\n# install\n\nInstall from PyPI:\n```\npip install imdown\n```\nor from GitHub:\n```\npip install git+https://github.com/LeSasse/imdown.git\n```\n\n\n# Write new files\n\n## Try out the example\n\nYou can try it out on the example provided in this repository. Go to the `example`\ndirectory:\n\n```\ngit clone https://github.com/LeSasse/imdown.git\ncd imdown/example\n```\n\nCollect all images from the `figures` directory and put them into a markdown file:\n\n```\nimdown figures -o markdown_files/all_filetypes.md\n```\nand see the result in [markdown_files/all_filetypes.md](example/markdown_files/all_filetypes.md).\nOr filter out a specific filetype only i.e. pdf's:\n\n```\nimdown figures -f pdf -o markdown_files/only_pdfs.md\n```\n\nYou can then manually adjust the markdown file and compile via [pandoc](https://pandoc.org/).\nIf you do not need to adjust it and just want the pdf, you can also skip the intermediate markdown file\nand pipe it straight into pandoc (of course for this you need [pandoc](https://pandoc.org/) installed!):\n\n```\nimdown figures -f pdf | pandoc -o output_pdfs/piped.pdf\n```\nand see the result in [output_pdfs/piped.pdf](example/output_pdfs/piped.pdf).\n\n## Adjust the paths written in the markdown output\n\nBy default `imdown` will write all the paths relative to the directory\nin which the markdown file will be written (or from current directory if the\nmarkdown is just printed to stdout). However, you may not always like to build\nyour final output format from the same directory as the markdown file, so you\ncan specifiy `-b, --build_directory`, so that all paths will be written relative\nfrom this directory:\n\n```\nimdown figures -b . -o markdown_files/build_directory_specified.md\n```\n\nCheck the result in [markdown_files/build_directory_specified.md](example/markdown_files/build_directory_specified.md)\nand you can see that the paths are relative not from the md file but from the\ndirectory you specified (i.e. the current directory). Note that of course the\nexample in the repository is therefore not able to show the pictures in that\nparticular md file. Alternatively, you can also simply use the `-a, --absolute`\nflag to write all paths as absolute paths.\n\n## Ignore paths or filenames based on a string\n\nYou can pass a string to the `-i, --ignore` flag. If any of the paths/filenames\nof the images include this string, it will be ignored.\nFor example:\n```\nimdown figures -i analysis1\n```\nwill result in:\n\n```\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n```\n\nYou can also ignore multiple strings, i.e.\n```\nimdown figures -f pdf png -i analysis1 analysis2\n```\nwill result in:\n\n```\n\n\n\n\n\n\n\n\n\n```\n\n## Walk only to a certain depth\n\nYou can specify how many levels the program should walk the directory tree.\nIf None (default) the program will walk all the way. Specify 0 to only consider\nfiles in the initial directory. For each level deeper add +1.\nFor example:\n\n```\nimdown figures -f pdf png -d 0\n```\nwill output nothing, as there are no files in the initial directory.\nHowever, specifiying one level will be enough to give the same output as the default\nin this case, as the program will go one level deeper (but there are no levels beyond\nthis in the example).\n```\nimdown figures -f pdf png -d 1\n```\n\n# Update manually adjusted markdowns\n\nNow imagine that you manually adjusted captions or text in one of the markdown files.\nBut you also added new plots to your directory and want to add them to you markdown or you want to include filetypes\nthat you did not include previously.\n\nFor example consider [markdown_files/manually_adjusted.md](example/markdown_files/manually_adjusted.md).\nThis is the markdown that I created only using pdf plots. I now also want to add all\npng's. I have adjusted the captions and added some text and of course I do not want to lose that text when\nadding new plots. In order to do this I can provide the adjusted file as a reference file as an \nadditional argument and add only the new plots. For example I can test it and print the\nupdated version to stdout:\n\n```\nimdown figures -f pdf png -r markdown_files/manually_adjusted.md\n```\n\nwhich should output:\n\n```markdown\n\n\nI have also added some text.\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n```\n\nNote that this outputs all paths as relative to the current directory, since\nyou are printing to stdout. The advantage is that the old paths aren't just valid\nfrom the reference file, but you can also write it to a new file, in which case\npaths will be written relative from that file:\n\n```\nimdown figures -f pdf png -o markdown_files/manually_adjusted_and_updated.md -r markdown_files/manually_adjusted.md\n```\nfor which you can find the result in [markdown_files/manually_adjusted_and_updated.md](example/markdown_files/manually_adjusted_and_updated).\n\nOf course you can also overwrite the reference file, but do that at your own risk.\nAnother advantage of this is, that you can take the reference file, update it with the \nnew plots, and pipe it straight into pandoc again, if you like:\n\n```\nimdown figures -f pdf png -r markdown_files/manually_adjusted.md | pandoc -o output_pdfs/piped_from_reference.pdf\n```\nYou can see the result at [output_pdfs/piped_from_reference.pdf](example/output_pdfs/piped_from_reference.pdf)\n",
"bugtrack_url": null,
"license": "",
"summary": "Collect images from a directory tree and add them to a markdown file.",
"version": "0.0.1.dev13",
"project_urls": {
"repository": "https://github.com/LeSasse/imdown"
},
"split_keywords": [
"pandoc",
"markdown",
"images"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "7c3b1d0d8d82151c51d2497dd109ff652833d524a0ccc5e27595a9adc858a4a8",
"md5": "989b5d0676a7062433e448013a706f1a",
"sha256": "7721f89ea45fd9a6ab6197d0d5ca4331ef88539279b02881504f8eeb43e3e841"
},
"downloads": -1,
"filename": "imdown-0.0.1.dev13-py3-none-any.whl",
"has_sig": false,
"md5_digest": "989b5d0676a7062433e448013a706f1a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 19648,
"upload_time": "2023-11-12T14:49:23",
"upload_time_iso_8601": "2023-11-12T14:49:23.242754Z",
"url": "https://files.pythonhosted.org/packages/7c/3b/1d0d8d82151c51d2497dd109ff652833d524a0ccc5e27595a9adc858a4a8/imdown-0.0.1.dev13-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "6bf7469e013b2fbe2b8ff0dd248e0561ee8d4d1fbd7a221c943699d3e3da0f9f",
"md5": "b7020b1e039a1f238e6ed06980e04ce5",
"sha256": "76f9c61c43f55dcb5d9e14c5b9ac39c727c70cf4905a16e56059f54fb1f00ff8"
},
"downloads": -1,
"filename": "imdown-0.0.1.dev13.tar.gz",
"has_sig": false,
"md5_digest": "b7020b1e039a1f238e6ed06980e04ce5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 466529,
"upload_time": "2023-11-12T14:49:24",
"upload_time_iso_8601": "2023-11-12T14:49:24.693491Z",
"url": "https://files.pythonhosted.org/packages/6b/f7/469e013b2fbe2b8ff0dd248e0561ee8d4d1fbd7a221c943699d3e3da0f9f/imdown-0.0.1.dev13.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-11-12 14:49:24",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "LeSasse",
"github_project": "imdown",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "imdown"
}
