Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/davidcavazos/md2ipynb
Markdown to Jupyter notebook converter.
https://github.com/davidcavazos/md2ipynb
Last synced: 2 months ago
JSON representation
Markdown to Jupyter notebook converter.
- Host: GitHub
- URL: https://github.com/davidcavazos/md2ipynb
- Owner: davidcavazos
- License: apache-2.0
- Created: 2019-06-20T21:24:23.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2020-08-25T16:13:58.000Z (over 4 years ago)
- Last Synced: 2024-10-08T13:27:50.250Z (3 months ago)
- Language: Python
- Homepage:
- Size: 157 KB
- Stars: 4
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# md2ipynb
Markdown to Jupyter Notebook converter.
## Setup
### [optional] Virtual environment
Make sure you have `virtualenv` installed.
```sh
pip install -U virtualenv
```
Create and activate a new `virtualenv`.
```sh
python -m virtualenv env
source env/bin/activate
```
> **Note**: Once you are all done, you can deactivate it by running `deactivate`.
### Installation
The easiest way to install is through `pip`.
```sh
pip install -U md2ipynb
```
### Example data
Now, to get some example data, we'll clone the repository.
```sh
# Clone the repository just to have access to the examples.
git clone [email protected]:davidcavazos/md2ipynb.git
cd md2ipynb
```
> *Note:* If you make modifications to the source code and want to use that,
> you can install it in "editable" (development) mode.
>
> ```sh
> pip install -e .
> ```
>
> For more information, see the [Contribution guide](CONTRIBUTING.md).
Installing the `md2ipynb` module will also install the `md2ipynb` command line tool.
For custom preprocessing steps or integration with Python scripts,
it is also available by importing the `md2ipynb` module from any Python script.
## Minimal example
* source: [hello.md](examples/pages/hello.md)
* code: [hello-world.py](examples/code/hello-world.py)
Here is a minimal example on how to convert a Markdown file.
By default, the output is printed into `stdout`.
```sh
md2ipynb examples/pages/hello.md
```
You can also specify an output path with the `-o` or `--output` option.
```sh
md2ipynb examples/pages/hello.md -o examples/notebooks/hello.ipynb
```
Here is the generated notebook on Colab and GitHub.
## Example
* source: [hello.md](examples/pages/hello.md)
* code: [hello-world.py](examples/code/hello-world.py)
* import: [license.md](examples/templates/license.md)
* import: [setup-py.md](examples/templates/setup-py.md)
* import: [cleanup.md](examples/templates/cleanup.md)
Here is a more complete example on specifying an output path, import sections,
variables, as well as more metadata for a Colab visualization.
```sh
md2ipynb examples/pages/hello.md \
-o examples/notebooks/hello.ipynb \
--imports examples/templates/license.md:0 \
examples/templates/setup-py.md:1 \
examples/templates/cleanup.md:-2 \
--var package=md2ipynb \
end_message="You're all done 🎉🎉" \
--notebook-title 'Hello md2ipynb!' \
--docs-url https://github.com/davidcavazos/md2ipynb \
--docs-logo-url https://www.tensorflow.org/images/GitHub-Mark-32px.png \
--github-ipynb-url https://github.com/davidcavazos/md2ipynb/blob/master/examples/notebooks/hello.ipynb
```
> *Note:* For more information on the available options, run `md2ipynb --help`.
Here is the generated notebook on Colab and GitHub.
Note that since we specified the `--github-ipynb-url`,
there is now an "Open in Colab" button in the GitHub ipynb file.
## Python example
* source: [hello.md](examples/pages/hello.md)
* code: [hello-world.py](examples/code/hello-world.py)
* import: [license.md](examples/templates/license.md)
* import: [setup-py.md](examples/templates/setup-py.md)
* import: [cleanup.md](examples/templates/cleanup.md)
The following example shows how to use `md2ipynb` as a Python module.
This example shows how to specify custom preprocessing steps, import sections,
use variables, as well as more metadata for a Colab visualization.
```py
import md2ipynb
def add_separators(paragraphs):
for p in paragraphs:
yield '---'
yield p
yield '---'
def replace(paragraphs, old, new):
for p in paragraphs:
yield p.replace(old, new)
# Create a new IPython notebook.
notebook = md2ipynb.new_notebook(
input_file='examples/pages/hello.md',
imports={
0: ['examples/templates/license.md'],
1: ['examples/templates/setup-py.md'],
-1: ['examples/templates/cleanup.md'],
},
variables={
'package': 'md2ipynb',
'end_message': "You're all done 🎉🎉",
},
notebook_title='Hello md2ipynb!',
docs_url='https://github.com/davidcavazos/md2ipynb',
docs_logo_url='https://www.tensorflow.org/images/GitHub-Mark-32px.png',
github_ipynb_url='https://github.com/davidcavazos/md2ipynb/blob/master/examples/notebooks/hello.ipynb',
# Additional steps can be run in the order specified.
# If the generator receives multiple arguments, they can be passed as a tuple.
steps=[
add_separators,
(replace, 'Hello', 'Hi'),
],
)
# Write the notebook to a file.
import nbformat
with open('examples/notebooks/hello-custom.ipynb', 'w') as f:
nbformat.write(notebook, f)
```
Here is the generated notebook on Colab and GitHub.
## Contributing
Contributions are welcome! For instructions on how to contribute,
please check the [Contribution guide](CONTRIBUTING.md).
