# Write your notebook content

Once activated, the MyST-NB Sphinx extension will automatically parse both
markdown (`.md`) and Jupyter notebooks (`.ipynb`) into your Sphinx site. If your
markdown files have [Jupytext metadata for MyST Notebooks](myst-nb/sphinx),
they will be converted to notebooks and optionally executed.

In any of these files, you may write [MyST Markdown](https://myst-parser.readthedocs.io).
This is an extension of CommonMark markdown that provides extra syntax for common
workflows in publishing, and extension points for extra functionality.

## Writing MyST Markdown

MyST Markdown is a flavor of markdown that gives you full access to all of the
functionality provided by Sphinx (such as roles and directives). In MyST-NB, this
is provided by the [MyST Parser](https://myst-parser.readthedocs.io/en/latest/), another
Sphinx extension that MyST-NB depends on.

You can write your MyST markdown in either regular markdown files (`.md`) or in
the markdown cells of Jupyter Notebooks (`.ipynb`).

:::{warning}
If you are using MyST-NB in your documentation, do not activate `myst-parser`. It will
be automatically activated by `myst-nb`.
:::

For more information about what you can write with MyST Markdown, see the
[MyST Parser syntax guide](https://myst-parser.readthedocs.io/en/latest/using/syntax.html).

## Write notebooks in pure markdown

In addition to supporting MyST Markdown inside of `.md` and `.ipynb` files, you can
also write Jupyter Notebooks entirelly with markdown by using
[MyST Markdown Notebooks](markdown.md). MyST Notebooks have a similar structure
to Jupyter Notebooks (`.ipynb`), but they are written with MyST Markdown syntax to
be easier to use with text editors.

To use MyST Notebooks with `myst_nb`, you'll need to add Jupytext metadata to your
MyST Notebooks. See [](myst-nb/sphinx) for more details.

## Parse extensions other than `.md` and `.ipynb`

You can change which files 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',
}
```

(myst/error-reporting)=

## Error reporting in Sphinx

When Sphinx encounters and error or raises a warning, it will print the location and source file of the text that generated that error.
This works slightly differently depending on whether you use markdown files or Jupyter Notebook files.

For markdown (`.md`) files, Sphinx will correctly report the line number that the error or warning is associated with:

```
source/path:4: (WARNING/2) Duplicate reference definition: abc
```

For Jupyter Notebook (`.ipynb`) files, these errors also correspond to a cell index.
To allow for this, we use a special format of line number corresponding to: `<CELL_INDEX> * 10000 + LINE_NUMBER`.

For example, the following error corresponds to **Cell 1, line 4**:

```
source/path:10004: (WARNING/2) Duplicate reference definition: abc
```