##// END OF EJS Templates
Remove mention of previous behaviour
onesandzeroes -
Show More
@@ -1,169 +1,168
1 1 .. _nbconvert:
2 2
3 3 Converting notebooks to other formats
4 4 =====================================
5 5
6 6 Newly added in the 1.0 release of IPython is the ``nbconvert`` tool, which
7 7 allows you to convert an ``.ipynb`` notebook document file into various static
8 8 formats.
9 9
10 10 Currently, ``nbconvert`` is provided as a command line tool, run as a script
11 11 using IPython. A direct export capability from within the
12 12 IPython Notebook web app is planned.
13 13
14 14 The command-line syntax to run the ``nbconvert`` script is::
15 15
16 16 $ ipython nbconvert --to FORMAT notebook.ipynb
17 17
18 18 This will convert the IPython document file ``notebook.ipynb`` into the output
19 19 format given by the ``FORMAT`` string.
20 20
21 21 The default output format is html, for which the ``--to`` argument may be
22 22 omitted::
23 23
24 24 $ ipython nbconvert notebook.ipynb
25 25
26 26 IPython provides a few templates for some output formats, and these can be
27 27 specified via an additional ``--template`` argument.
28 28
29 29 The currently supported export formats are:
30 30
31 31 * ``--to html``
32 32
33 33 - ``--template full`` (default)
34 34
35 35 A full static HTML render of the notebook.
36 36 This looks very similar to the interactive view.
37 37
38 38 - ``--template basic``
39 39
40 40 Simplified HTML, useful for embedding in webpages, blogs, etc.
41 41 This excludes HTML headers.
42 42
43 43 * ``--to latex``
44 44
45 45 Latex export. This generates ``NOTEBOOK_NAME.tex`` file,
46 46 ready for export.
47 47
48 48 - ``--template article`` (default)
49 49
50 50 Latex article, derived from Sphinx's howto template.
51 51
52 52 - ``--template report``
53 53
54 54 Latex report, providing a table of contents and chapters.
55 55
56 56 - ``--template basic``
57 57
58 58 Very basic latex output - mainly meant as a starting point for custom templates.
59 59
60 60 * ``--to pdf``
61 61
62 Generates a PDF via latex. Replaces ``--to latex --post PDF``, which is deprecated.
63 Supports the same templates as ``--to latex``.
62 Generates a PDF via latex. Supports the same templates as ``--to latex``.
64 63
65 64 * ``--to slides``
66 65
67 66 This generates a Reveal.js HTML slideshow.
68 67 It must be served by an HTTP server. The easiest way to do this is adding
69 68 ``--post serve`` on the command-line. The ``serve`` post-processor proxies
70 69 Reveal.js requests to a CDN if no local Reveal.js library is present.
71 70 To make slides that don't require an internet connection, just place the
72 71 Reveal.js library in the same directory where your_talk.slides.html is located,
73 72 or point to another directory using the ``--reveal-prefix`` alias.
74 73
75 74 * ``--to markdown``
76 75
77 76 Simple markdown output. Markdown cells are unaffected,
78 77 and code cells indented 4 spaces.
79 78
80 79 * ``--to rst``
81 80
82 81 Basic reStructuredText output. Useful as a starting point for embedding notebooks
83 82 in Sphinx docs.
84 83
85 84 * ``--to script``
86 85
87 86 Convert a notebook to an executable script.
88 87 This is the simplest way to get a Python (or other language, depending on the kernel) script out of a notebook.
89 88 If there were any magics in an IPython notebook, this may only be executable from
90 89 an IPython session.
91 90
92 91 * ``--to notebook``
93 92
94 93 .. versionadded:: 3.0
95 94
96 95 This doesn't convert a notebook to a different format *per se*,
97 96 instead it allows the running of nbconvert preprocessors on a notebook,
98 97 and/or conversion to other notebook formats. For example::
99 98
100 99 ipython nbconvert --to notebook --execute mynotebook.ipynb
101 100
102 101 will open the notebook, execute it, capture new output, and save the result in
103 102 :file:`mynotebook.nbconvert.ipynb`.
104 103
105 104 ::
106 105
107 106 ipython nbconvert --to notebook --nbformat 3 mynotebook
108 107
109 108 will create a copy of :file:`mynotebook.ipynb` in :file:`mynotebook.v3.ipynb`
110 109 in version 3 of the :ref:`notebook format <nbformat>`.
111 110
112 111 If you want to convert a notebook in-place,
113 112 you can specify the ouptut file to be the same as the input file::
114 113
115 114 ipython nbconvert --to notebook mynb --output mynb
116 115
117 116 Be careful with that, since it will replace the input file.
118 117
119 118 .. note::
120 119
121 120 nbconvert uses pandoc_ to convert between various markup languages,
122 121 so pandoc is a dependency when converting to latex or reStructuredText.
123 122
124 123 .. _pandoc: http://johnmacfarlane.net/pandoc/
125 124
126 125 The output file created by ``nbconvert`` will have the same base name as
127 126 the notebook and will be placed in the current working directory. Any
128 127 supporting files (graphics, etc) will be placed in a new directory with the
129 128 same base name as the notebook, suffixed with ``_files``::
130 129
131 130 $ ipython nbconvert notebook.ipynb
132 131 $ ls
133 132 notebook.ipynb notebook.html notebook_files/
134 133
135 134 For simple single-file output, such as html, markdown, etc.,
136 135 the output may be sent to standard output with::
137 136
138 137 $ ipython nbconvert --to markdown notebook.ipynb --stdout
139 138
140 139 Multiple notebooks can be specified from the command line::
141 140
142 141 $ ipython nbconvert notebook*.ipynb
143 142 $ ipython nbconvert notebook1.ipynb notebook2.ipynb
144 143
145 144 or via a list in a configuration file, say ``mycfg.py``, containing the text::
146 145
147 146 c = get_config()
148 147 c.NbConvertApp.notebooks = ["notebook1.ipynb", "notebook2.ipynb"]
149 148
150 149 and using the command::
151 150
152 151 $ ipython nbconvert --config mycfg.py
153 152
154 153
155 154 LaTeX citations
156 155 ---------------
157 156
158 157 ``nbconvert`` now has support for LaTeX citations. With this capability you
159 158 can:
160 159
161 160 * Manage citations using BibTeX.
162 161 * Cite those citations in Markdown cells using HTML data attributes.
163 162 * Have ``nbconvert`` generate proper LaTeX citations and run BibTeX.
164 163
165 164 For an example of how this works, please see the citations example in
166 165 the nbconvert-examples_ repository.
167 166
168 167 .. _nbconvert-examples: https://github.com/ipython/nbconvert-examples
169 168
General Comments 0
You need to be logged in to leave comments. Login now