# Linking documents

## Referencing another lecture

To add a link to another document in the same lecture series you can use standard markdown links. 

Here is an example link:

```md
[another document](figures)
```

which will render as: [another document](figures). 

In many cases it can be useful to automatically use the title of the referenced page.

In this case then you should leave the `title text` field blank such as:

```md
[](figures)
```

which will render as: [](figures). 

## Referencing a lecture in a different lecture series

```{warning}
To reference a document in a different lecture series the repo needs to have `intersphinx` 
configured in `_config.yml`. Please consult the development team.
```

Documents in another lecture series can be referenced using `{doc}` links. 

For example, this repository has setup intersphinx in `_config.yml` to provide
linking to the {doc}`intro:intro`. 

```yaml
intersphinx_mapping: 
    intro: 
    - "https://intro.quantecon.org/"
    - null
```

To setup a link you can use:

```md
{doc}`this lecture on linear equations<intro:linear_equations>`
```

which will render as: {doc}`this lecture on linear equations<intro:linear_equations>`

```{note}
The `intro:` is an important part of the link. It is determined by the `_config.yml` settings
for intersphinx, so you may need to review `_config.yml` to understand what link stub to use. 
```

In many cases it can be useful to automatically use the title of the referenced page.

This can be done by just specifying the link such as:

```md
{doc}`intro:linear_equations`
```

which will use the full title of the lecture: {doc}`intro:linear_equations`

```{tip}
You will note the later link doesn't include the `<` and `>` brackets. 
```

## Using lecture titles in `{doc}` references

Prefer the auto-fill forms shown above — leaving the link text empty so mystmd inserts the referenced lecture's title automatically:

```md
[](ar1_bayes)
```

```md
{doc}`intro:linear_equations`
```

This keeps the link text in sync if a lecture is renamed and avoids generic placeholder text like "this quantecon lecture". If you do need custom link text, use the actual lecture title rather than generic phrasing.

## Standard `intersphinx` definitions

The standard `intersphinx` definitions are:

| code | target lecture |
|------|----------------|
| programming | https://python-programming.quantecon.org/ |
| intro | https://intro.quantecon.org/ |
| intermediate | https://python.quantecon.org/ |
| advanced | https://python-advanced.quantecon.org/ |
| jax | https://jax.quantecon.org/ |