Skip to content

Commit 65687a3

Browse files
committed
simplify submodules part and clarify not in workflow
1 parent e86e597 commit 65687a3

File tree

1 file changed

+9
-9
lines changed

1 file changed

+9
-9
lines changed

book/features/external_toc.md

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
(teachbooks-package)=
1+
(external-toc)=
22
# Sharing content between books in table of contents
33

44
```{admonition} User types
@@ -9,14 +9,14 @@ This page is useful for user type 3-5.
99
{bdg-secondary}`Python Package: teachbooks`
1010

1111
## Introduction
12-
When creating books, you might want to reuse material from other people or from other books you made. In some cases you might even want to have the exact same material into your book. You could do so by manually copying material over. However, whenever the source material is updated, you have to do that again. As an alternative, you can use the underlying git system to refer to the source file directly. This allows you to pick a specific version, or keep the most up-to-date version of it. This pages explains how to do so directly in the table of contents using the TeachBooks package.
13-
14-
Previously, this was implemented using [submodules](../external/Nested-Books/README.md), but this implementation was more difficult to use. However, the approach using submodules allows to embed pages which:
15-
- refer to content in the `_static` folder of the other book.
16-
- include local images referenced with raw-HTML code.
17-
- are part of a private book.
18-
- _automatically_ notify you upon changes in the source book using Github's "Dependabot".
19-
These features are not incorporated in the new workflow yet.
12+
13+
When creating books, you might want to reuse material from other people or from other books you made. In some cases you might even want to have the exact same material into your book. You could do so by manually copying material over. However, whenever the source material is updated, you have to do that again. As an alternative, you can use the underlying git system to refer to the source file directly. This allows you to pick a specific version, or keep the most up-to-date version of it. This pages explains how to do so directly in the table of contents using the **External Content** (or **External TOC**) feature which is part of the TeachBooks Python package.
14+
15+
Previously, this book feature was implemented using [submodules](../external/Nested-Books/README.md), but the implementation was more difficult to use. Despite this, submodules are still a widely used Git feature that can be very useful for book authors, so check out the [submodules page](../external/Nested-Books/README.md) to learn more, especially if the External TOC tool does not satisfy your needs.
16+
17+
```{warning}
18+
The External TOC features are not incorporated in the new deploy book workflow yet (this will happen once the workflow specifies `teachbooks>=0.2.0`).
19+
```
2020

2121
## What does it do?
2222

0 commit comments

Comments
 (0)