docs(ipynb): documents media related tips & tricks #7749
Conversation
See discussion in #7745, in particular, #7745 (comment) #7745 (comment)
|
@jgm, I take the approach that simply document this behavior. Let me know if you think this is enough. |
ickc
changed the title
|
@jgm, did you have a chance to look at the proposed doc and see if this is ok? Thanks. |
MANUAL.txt
Outdated
| ## Image media | ||
|
|
||
| When the ipynb input has media such as svg, png, pdf, | ||
| you may want to use `--self-contained` for any of the supported | ||
| output formats including HTML, or use `--extract-media` in general. | ||
|
|
||
| ## Javascript media | ||
|
|
||
| When converting from ipynb, some Jupyter extensions, | ||
| especially those that uses javascript for visualization, | ||
| expects the presence of | ||
| [`require.js`](https://github.com/requirejs/requirejs). | ||
| In this case when converting say from ipynb to html, | ||
| you can add the following | ||
| either via `header-includes` in metadata or | ||
| `--include-in-header` on the command line: | ||
|
|
||
| ``` | ||
| <script src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.6/require.min.js"> | ||
| </script> | ||
| ``` | ||
|
|
||
| such as | ||
|
|
||
| ``` | ||
| pandoc -s -o require.html require.ipynb \ | ||
| -V header-includes='<script src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.6/require.min.js"></script>' | ||
| ``` | ||
|
|
There was a problem hiding this comment.
I'm reluctant to add this to the manual, which is already overly long.
Perhaps this information should be in the FAQ on the website?
There was a problem hiding this comment.
I tried to shorten the description to be more succinct.
I think people are more used to get information like this in the manual than the FAQ,
(where I never went to look for information, but I should now knowing it exists.)
If you insist to make it to FAQ instead,
is it https://pandoc.org/faqs.html ?
Should it be committed to https://github.com/jgm/pandoc-website and which file?
There was a problem hiding this comment.
FAQs live in this repository, in doc/faqs.md.
They get copied to the website from this repo on each release.
There was a problem hiding this comment.
Is there a specific error people would get that would tell us that they need require.js? If so, it would be natural to have a FAQ like "I'm getting such-and-such error when I try to use JavaScript in ipynb. What does this mean?"
There was a problem hiding this comment.
I believe it will just show as an empty image, which can still be the hint to use require.js in the FAQ.
(Of course there will be error message in the console if they open the debug tool, but probably the FAQ is for those who don't.)
|
We will rebase after the discussion above is settle. |
|
I added a FAQ. |
For
require.js, See discussion in #7745, in particular,#7745 (comment)
#7745 (comment)
I added a commit to documents the use of
--extract-mediaor--self-containedtoo. nbconvert behavior is similar to using--self-containedhere.