Linking and Interlinking
- Links between step-by-step guides
-
Links between step-by-step guides and the TYPO3 documentation
- How to find a guide or documentation page to link to
- 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 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
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.Tip
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 anUpperCamelCase.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
- Use the TYPO3 Documentation search function — 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.
- 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/) - 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 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.