# Linking and Interlinking - [Links between step-by-step guides](#links-between-step-by-step-guides) - [Links between step-by-step guides and the TYPO3 documentation](#links-between-step-by-step-guides-and-the-typo3-documentation) - [From step-by-step guides to the TYPO3 documentation](#from-step-by-step-guides-to-the-typo3-documentation) - [From the TYPO3 documentation to step-by-step guides](#from-the-typo3-documentation-to-step-by-step-guides) - [How to find a guide or documentation page to link to](#how-to-find-a-guide-or-documentation-page-to-link-to) - [How to link to missing guides](#how-to-link-to-missing-guides) Step-by-step guides don’t exist in a vacuum, and linking to and from other content multiplies their usefulness. In addition to linking between step-by-step guides, there are two main document types to interlink with: the encyclopedic TYPO3 documentation, and [SkillDisplay](https://www.skilldisplay.eu/) skills. ## Links between step-by-step guides Inside a step-by-step guide you will normally link to other step-by-step guides in these three places: * In the *Prerequisites* section, if the guide you link to must be completed before starting the current guide. * In the *Next steps* section, so the reader can continue to other guides after finishing the current guide. * Within the steps, if the step requires existing knowledge, for example: `Create a new page as described in [Create a new page](CreateANewPage.md).` > [!TIP] > **Just use the step-by-step guide's file name when linking.** Since all step-by-step guides have unique titles (and thus unique file names) the path will automatically be inserted when before the page is rendered. This also makes it easy to move files within the structure. > > **Example**: Use `[Change TYPO3's Default Language](ChangeTypo3sDefaultLanguage.md)` instead of `[Change TYPO3's Default Language](../../20Multilingual/ChangeTypo3sDefaultLanguage.md)`. > [!TIP] > **Link to non-existent step-by-step guides.** If a step-by-step guide doesn't exist yet, linking to it will automatically add it to the list of missing guides. Please use the guide's title as the link text. The file name is always an `UpperCamelCase.md` version of the title. ## Links between step-by-step guides and the TYPO3 documentation Step-by-step guides and encyclopedic documents should link to each other, in both directions. ### From step-by-step guides to the TYPO3 documentation Step-by-step guides should point to relevant documentation pages for these reasons: * To let the reader go into details if needed * To avoid repeating content that is already available * To keep the guides focused on the task Inside a guide, linking to the documentation can be done in three ways: * Within the text, as embedded links * As a callout after a paragraph, such as: *For a complete overview of TypoScript options, see the [TypoScript reference].* * At the end of the guide, the Resources section can contain accumulated links to the TYPO3 documentation. ### From the TYPO3 documentation to step-by-step guides The opposite direction, from the documentation to step-by-step guides, is equally important, as it can prevent beginners from choosing the wrong kind of documentation for starting their journey of learning TYPO3. If a step-by-step guide exists for a given page of the documentation, this page or section should contain a “guide available” banner: *Step-by-Step Guide Available* *Learn how to implement this feature with our step-by-step guide: [Creating Custom Content Elements]* ## How to find a guide or documentation page to link to **Do a search** * Check the [Step-by-Step Guide registry](../../80GuidesRegistry/Index.md) * Use the [TYPO3 Documentation search function](https://docs.typo3.org/search/) — it is powerful and comprehensive. Try a few different terms or phrasing variations. If your search turns up nothing useful, that may be a good sign that your guide really is needed. **See what others have done** Look at step-by-step guides written by other contributors that sit before or alongside yours in the structure. See what documentation pages they link to. This saves you the trouble of searching the docs from scratch. If your guide builds on or shares a task with a similar guide, chances are it will already have referenced the same concepts, terminology, or documentation pages that you’re looking for. For example, creating pages, adding content elements, accessing page properties, etc. ## How to link to missing guides Sometimes, while writing a step-by-step guide, you’ll need to reference a related guide that doesn’t exist yet. This might happen: * In the **prerequisite section**. For example, a skill or configuration that the learner needs first. * **During a task**. For example, “Before continuing, make sure you’ve [Created a custom backend layout\]” — but that guide isn’t written yet. That’s okay! Missing guides are part of a growing system, and it’s important not to lose your flow or get side-tracked. Here’s how to handle them. 1. **Link to the missing guide anyway.** If the guide doesn’t exist, link to the title it should have as if it does. Use the normal way you'd insert a link using MarkDown syntax: `[Link text](relative/path-to-guide/)` 2. **Add the missing guide to the structure.** Don’t worry about writing the guide yourself — just give it a logical placeholder. See [How to Place Guides in the Structure](../30UnderstandingTheStructure/20PlaceGuidesInTheStructure.md) for more information. **Missing guides will be tracked automatically.** An automated script keeps track of missing guides by tracking links to step-by-step guides that don’t yet exist (essentially, broken internal links within the repository). These will be listed as not-yet-created, with the option to click a link to create them.