Add an example with custom notebook metadata

CHANGELOG.md

@@ -1,6 +1,9 @@
 1.4.2 (2020-04-??)
 ------------------
 
+**Added**
+- Added an example with custom notebook metadata (#469)
+
 **Changed**
 - Use `os.path.samefile` when searching for the kernel that corresponds to the current environment (`--set-kernel -`)
 - The outputs from the `.ipynb` file are matched with the input cells from the text file with less strict rules. In this version, a search and replace on the text file will not remove the outputs any more (#464).

docs/formats.md

@@ -8,7 +8,7 @@ Jupytext supports conversion between the `.ipynb` format and many different form
 
 Jupytext can save notebooks as [Markdown](https://daringfireball.net/projects/markdown/syntax) documents. This format is well adapted to tutorials, books, or more generally notebooks that contain more text than code. Notebooks represented in this form are well rendered by most Markdown editors or renderers, including GitHub.
 
-Like all the Jupytext formats, Jupytext Markdown notebooks start with an (optional) YAML header. This header is used to store selected notebook metadata like the kernel information, together with Jupytext's format and version information. If you'd like to store more (or less) notebook metadata, please refer to the paragraph on [metadata filtering](#metadata-filtering).
+Like all the Jupytext formats, Jupytext Markdown notebooks start with an (optional) YAML header. This header is used to store selected notebook metadata like the kernel information, together with Jupytext's format and version information.
 ```
 ---
 jupyter:
@@ -25,6 +25,9 @@ jupyter:
 ---
 ```
 
+You can add custom notebook metadata like `author` or `title` under the `jupyter:` section, it will be synchronized with the notebook metadata. 
+And if you wish to export more metadata from the notebook, have a look at the paragraph on [metadata filtering](#metadata-filtering).
+
 In the Markdown format, markdown cells are inserted verbatim and separated with two blank lines.
 
 If you'd like that cell breaks also occurs on Markdown headers, add a `split_at_heading: true` entry in the `jupytext` section in the YAML header, or if you want that option to be the default for all Markdown documents in Jupyter, activate the option on Jupytext's content manager:
@@ -307,7 +310,9 @@ Our sample notebook is also represented in `sphinx` format [here](https://github
 
 All the Jupytext formats (except Sphinx Gallery scripts) store a selection of the notebook metadata in a YAML header at the top of the text file. By default, Jupytext only includes the `kernelspec` and `jupytext` metadata (the remaining notebook metadata are preserved in the `.ipynb` document when you use paired notebook). 
 
-If you want to include more (or less) jupyter metadata here, add a `notebook_metadata_filter` option to the `jupytext` metadata. The value for `notebook_metadata_filter` is a comma separated list of additional/excluded (negated) entries, with `all` a keyword that allows to exclude all entries. For instance, if you don't want to store any notebook metadata in the text file, use `notebook_metadata_filter: -all`. If you want to store the whole, unfiltered notebook metadata then use `notebook_metadata_filter: all`. And if you want the default, plus a few specific section, use e.g. `notebook_metadata_filter: section_one,section_two`.
+If you want to include more (or less) jupyter metadata here, add a `notebook_metadata_filter` option to the `jupytext` metadata.
+The additional metadata will be added to the `jupyter:` section in the YAML header (or, at the root of the YAML header for the `md:pandoc` and `md:myst` formats).
+The value for `notebook_metadata_filter` is a comma separated list of additional/excluded (negated) entries, with `all` a keyword that allows to exclude all entries. For instance, if you don't want to store any notebook metadata in the text file, use `notebook_metadata_filter: -all`. If you want to store the whole, unfiltered notebook metadata then use `notebook_metadata_filter: all`. And if you want the default, plus a few specific section, use e.g. `notebook_metadata_filter: section_one,section_two`.
 
 Similarly, cell metadata can be filtered with the `cell_metadata_filter` option. To minimize the differences when a notebook is edited, Jupytext's default cell metadata filter does not include the `autoscroll`, `collapsed`, `scrolled`, `trusted` and `ExecuteTime` cell metadata in the text representation.
 

docs/using-cli.md

@@ -58,7 +58,7 @@ If you want to preserve (or filter out) certain notebook or cell metadata, chang
 jupytext --to md --update-metadata '{"jupytext": {"notebook_metadata_filter":"all"}}' notebook.ipynb
 ```
 
-Read more on the default and possible values for the metadata filters in [this section](using-server.md#metadata-filtering).
+Read more on the default and possible values for the metadata filters in [this section](using-server.html#metadata-filtering).
 
 
 ## Jupytext as a Git pre-commit hook

tests/test_read_simple_markdown.py

@@ -694,3 +694,34 @@ def test_update_metadata_filter_2(
     nb = jupytext.reads(org, 'md')
     text = jupytext.writes(nb, 'md')
     compare(text, target)
+
+
+def test_custom_metadata(no_jupytext_version_number,
+                         nb=new_notebook(metadata={
+                             "author": "John Doe",
+                             "title": "Some serious math",
+                             "jupytext": {
+                                 "notebook_metadata_filter": "title,author"
+                             },
+                             "kernelspec": {
+                                 "display_name": "Python 3",
+                                 "language": "python",
+                                 "name": "python3"
+                             }}),
+                         md="""---
+jupyter:
+  author: John Doe
+  jupytext:
+    notebook_metadata_filter: title,author
+  kernelspec:
+    display_name: Python 3
+    language: python
+    name: python3
+  title: Some serious math
+---
+"""):
+    """Here we test the addition of custom metadata, cf. https://github.com/mwouts/jupytext/issues/469"""
+    md2 = jupytext.writes(nb, 'md')
+    compare(md2, md)
+    nb2 = jupytext.reads(md, 'md')
+    compare_notebooks(nb2, nb)