📚👌‼️: Improve documentation and usability

docs/authoring/basics.md

@@ -0,0 +1,122 @@
+
+(authoring/intro)=
+# The basics
+
+## Default file formats
+
+As well as writing in the Sphinx default format, [RestructuredText](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html) (`.rst`), loading `myst_nb` will also parse:
+
+- Markdown files (`.md`)
+- Jupyter notebooks (`.ipynb`)
+- MyST-NB text-based notebooks (`.md` + top-matter)
+
+## Custom file extensions
+
+You can change which file extensions are parsed by MyST-NB using
+the [source_suffix](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-source_suffix) option in your `conf.py`, e.g.:
+
+```python
+extensions = ["myst_nb"]
+source_suffix = {
+    '.rst': 'restructuredtext',
+    '.ipynb': 'myst-nb',
+    '.myst': 'myst-nb',
+}
+```
+
+## Other notebook formats
+
+See the [](write/custom_formats) section, for how to integrate other Notebook formats into your build, and integration with [jupytext](https://github.com/mwouts/jupytext).
+
+## MyST Markdown
+
+For all file formats, Markdown authoring is the backbone of MyST-NB.
+By default, the MyST flavour of Markdown is enabled,
+which extends [CommonMark](https://commonmark.org/) with RST inspired syntaxes to provide the additional functionality required for technical writing.
+
+In particular MyST adds targets, roles and directives syntax, allowing you to utilise all available Docutils/Sphinx features:
+
+::::{grid} 2
+:gutter: 1
+
+:::{grid-item-card} RestructuredText
+
+```
+.. _target:
+Header
+------
+
+:role-name:`content`
+
+.. directive-name:: argument
+   :parameter: value
+
+   content
+```
+:::
+
+:::{grid-item-card} MyST Markdown
+
+````
+(target)=
+# Header
+
+{role-name}`content`
+
+```{directive-name} argument
+:parameter: value
+
+content
+```
+````
+:::
+::::
+
+:::{seealso}
+See the [](authoring/jupyter-notebooks) section, for more details on how to author Jupyter notebooks.
+:::
+
+## Text-based notebooks
+
+MyST-NB text-based notebooks are a special format for storing Jupyter notebooks in a text file.
+They map directly to a Notebook file, without directly storing the code execution outputs.
+
+To designate a Markdown file as a text-based notebook, add the following top-matter to the start of the file:
+
+```yaml
+---
+file_format: mystnb
+kernelspec:
+  name: python3
+---
+```
+
+The `kernelspec.name` should relate to a [Jupyter kernel](https://github.com/jupyter/jupyter/wiki/Jupyter-kernels) installed in your environment.
+
+Code cells are then designated by the `code-cell` directive:
+
+````markdown
+```{code-cell}
+:tags: [my-tag]
+
+print("Hello world!")
+```
+````
+
+and Markdown can be split into cells by the `+++` break syntax:
+
+```markdown
+Markdown cell 1
+
++++ {"tags": ["my-tag"]}
+
+Markdown cell 2, with metadata tags
+```
+
+:::{seealso}
+See the [](authoring/text-notebooks) section, for more details on text-based notebooks, and integration with [jupytext](https://jupytext.readthedocs.io).
+:::
+
+## Configuration
+
+...

docs/examples/custom-formats.Rmd → docs/authoring/custom-formats.Rmd

@@ -8,8 +8,9 @@ jupyter:
     name: python3
 ---
 
-(examples/custom_formats)=
-# Custom Notebook Formats
+(write/custom_formats)=
+
+# Custom Formats
 
 You can designate additional file types to be converted to Notebooks, and then executed / parsed in the same manner as regular Notebooks, by adding the following configuration to your `conf.py`:
 
@@ -33,7 +34,7 @@ nb_custom_formats = {
 
 :::{important}
 
-By default, Markdown cells in the Notebook will be parsed using the same MyST parser configuration as for other Markdown files ([see available configuration options](config/reference)).
+By default, Markdown cells in the Notebook will be parsed using the same MyST parser configuration as for other Markdown files ([see available configuration options](config/intro)).
 
 But, if this is incompatible with your file format, then you can specify for the Markdown to be parsed as **strictly CommonMark**, using a third argument:
 

docs/authoring/index.md

@@ -0,0 +1,12 @@
+# Authoring
+
+Create content in one or more formats.
+
+```{toctree}
+:maxdepth: 1
+
+basics
+jupyter-notebooks
+text-notebooks
+custom-formats
+```

docs/examples/basic.md → docs/authoring/jupyter-notebooks.md

@@ -1,26 +1,23 @@
 ---
-jupytext:
-  text_representation:
-    extension: .md
-    format_name: myst
-    format_version: '0.8'
-    jupytext_version: '1.4.1'
+file_format: mystnb
 kernelspec:
-  display_name: Python 3
-  language: python
   name: python3
 ---
 
-# An example Jupyter Notebook
+(authoring/jupyter-notebooks)=
+# Jupyter Notebooks
 
 This notebook is a demonstration of directly-parsing Jupyter Notebooks into
 Sphinx using the MyST parser.[^download]
 
-[^download]: This notebook can be downloaded as
-            **{nb-download}`basic.ipynb`** and {download}`basic.md`
+[^download]: This notebook can be downloaded as **{nb-download}`jupyter-notebooks.ipynb`** and {download}`jupyter-notebooks.md`
 
 ## Markdown
 
+:::{seealso}
+For more information about what you can write with MyST Markdown, see the
+[MyST Parser syntax guide](myst:syntax/syntax).
+:::
 
 ### Configuration
 
@@ -40,6 +37,11 @@ myst_enable_extensions = [
 myst_url_schemes = ("http", "https", "mailto")
 ```
 
+:::{note}
+Loading the `myst_nb` extension also activates the [`myst_parser`](myst:index) extension, for enabling the MyST flavour of Markdown.
+It is not required to add this explicitly in the list of `extensions`.
+:::
+
 ### Syntax
 
 As you can see, markdown is parsed as expected. Embedding images should work as expected.