An nbconvert orgmode-exporter
Project description
nbcorg - A jupyter notebook to orgmode exporter for nbconvert
This is an nbconvert exporter to convert an ipython/jupyter notebook to orgmode with multiple options for treating source code and output blocks.
Installation and getting started
nbcorg can be installed from the command line with pip, e.g,
pip install nbcorg
This should install the software with dependencies, as well as create entry points for the orgmode exporters in nbconvert.
Using nbcorg
Once installed, the orgmode exporters can be selected using the nbconvert --to
switch, e.g,
jupyter nbconvert --to orgmode mynotebook.ipynb
If you'd rather run from source without installation, you may do so from the nbcorg directory using the full qualified name as described in the nbconvert documentation, e.g,
jupyter nbconvert --to nbcorg.OrgmodeExporter mynotebook.ipynb
Included exporters
nbcorg functionality can be tuned using command line switches, as described below, however for convenience the package includes a couple named exporters with different default values for these.
orgmode
(nbcorg.OrgmodeExporter
)
This is the base exporter with default values for options and switches as described below
orgmode_babel
(nbcorg.OrgmodeBabelExporter
)
Ignores all output and appends :session :results output
to code blocks. Useful if a notebook should be converted to a literate programming org file. Note that the source code language is at the moment derived from notebook metadata, and for instance an ipython session is given as 'python', meaning that if you use cell magic you may need to do some tweaks to get it to work.
This a convenience exporter, running
jupyter nbconvert --to orgmode-babel mynotebook.ipynb
is the same as
jupyter nbconvert --to orgmode --OrgmodeExporter.src_block_options=':session :results output' --OrgmodeExporter.exclude_output=True
Configuration options
For a list of nbconfig configuration options also applicable to the orgmode exporters see the nbconvert manual for exporter and preprocessor options. (In particular those applicable to TemplateExporter
and ExtractOutputPrecprocessor
.)
nbcorg.OrgmodeExporter
defines also the following additional options:
--OrgmodeExporter.exclude_execute_result=<Bool>
Default: False
Do not include execution results in output data.
Execute results are special outputs separate from display data. The
[matplotlib.Y.Z at 0x123456789ABCDEF]
kind of strings in the notebook
when plotting a matplotlib figure is one example.
--OrgmodeExporter.exclude_raw=<Bool>
Default: False
This allows you to exclude raw cells from all templates if set to True.
--OrgmodeExporter.html_data_as=<Unicode>
Default: export
How HTML output data should be handled.
Allowed values:
export
- Enclose HTML in#+BEGIN_EXPORT html ...
-block.example
- Enclose HTML in#+BEGIN_EXAMPLE ...
-block.import
- Use pandoc to convert HTML to org. Results may vary... Much of likely still returned as HTML by pandoc and enclosed in+#BEGIN_HTML...
-blocks.
--OrgmodeExporter.input_drawer_name=<Unicode>
Default: INPUT
Drawer name for input cell content.
Only applicable if OrgmodeExporter.use_input_drawer=True
. Input cell
content will be placed in an org drawer of this name.
--OrgmodeExporter.javascript_data_as=<Unicode>
Default: html
How javascript output data should be handled.
Allowed values:
html
Place the js code in HTML <SCRIPT> tag and create placementinside#+BEGIN_EXPORT html ...
block.source
Place js code inside#+BEGIN_SRC js
-block.example
Enclose javascript in#+BEGIN_EXAMPLE ...
-block.ignore
- Ignore javascript blocks.
--OrgmodeExporter.latex_data_as=<Unicode>
Default: export
How LaTeX output data should be handled.
Allowed values:
- export - Enclose LaTeX in
#+BEGIN_EXPORT latex ...
-block. - example - Enclose LaTeX in
#+BEGIN_EXAMPLE ...
-block. - import - Use pandoc to convert LaTeX to org. Results may vary... pandoc likely wraps it in
#+BEGIN_SRC latex
-blocks.
--OrgmodeExporter.markdown_data_as=<Unicode>
Default: import
How markdown output data should be handled.
Allowed values:
example
- Enclose markdown in#+BEGIN_EXAMPLE ...
-block.import
- Use pandoc to convert markdown to org.
--OrgmodeExporter.output_drawer_name=<Unicode>
Default: RESULTS
Drawer name for output cell content.
Only applicable if OrgmodeExporter.use_output_drawer=True
. Output cell
content will be placed in an org drawer of this name.
--OrgmodeExporter.src_block_options=<Unicode>
Default: `` (empty string)
String of org src block extra options. This string will be added after the language name in all input cell source code blocks. Input code will be wrapped in a block on the form
#+BEGIN_SRC {{ lang }} {{src_block_options}}
{{ code }}
#+END_SRC
where lang
and code
is given by the notebook.
This option is useful to add org-babel options so that source blocks can be
executed from org-mode as well.
E.g. OrgmodeExporter.src_block_options=':session :results output'
which
will instruct org-babel to execute each source block in a session just like
a jupyter notebook.
(See org-babel for more information, and note that further configuration may
be needed to get ipython specifics, such as cell magic, to work.)
--OrgmodeExporter.supported_raw_as_export=<Bool>
Default: True
Wrap raw LaTeX and HTML cells in org export blocks.
Standard behaviour for nbconvert exporters when dealing with raw cells is
to include mime types requiring no conversion verbatim, while ignoring any
other ones. The mime-types to include is given by the configuration option
raw_mimetypes
, which for orgmode defaults to 'text/x-org' and ''
(corresponding to None Raw NBConvert Format
). However, similar to the
jupyter notebook, orgmode has the ability to mark blocks for inclusions
verbatim when exporting to a set of supported formats (currently HTML and
LaTeX). It therefore makes sense to convert raw cells in these formats to
the corresponding raw blocks. When supported_raw_as_export
is set to
True
the mime types 'text/html' and 'text/latex' are added to
raw_mimetypes
, and HTML and LaTeX raw cells are wrapped in export blocks
rather than included verbatim (other raw cell content is still represented
verbatim). When supported_raw_as_export
is set to False
this
functionality is turned off and only cells with mime types in
raw_mimetypes
are included.
--OrgmodeExporter.use_input_drawer=<Bool>
Default: False
If True, input cell contents are placed in drawers.
--OrgmodeExporter.use_output_drawer=<Bool>
Default: False
If True, output cell contents are placed in drawers.
Dependencies
nbcorg is dependent on the following software
Authors
- Lukas Ahrenberg
License
This project is licensed under the Modified BSD License. See LICENSE for text.
Project details
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.