Skip to content

Commit 51f63ac

Browse files
linawolflinawolf
committed
[FEATURE] Convert external permalinks to references during rendering
Also offer Markdown links
1 parent 2774f77 commit 51f63ac

File tree

53 files changed

+728
-237
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

53 files changed

+728
-237
lines changed

‎packages/typo3-docs-theme/assets/js/link-reference-modal.js

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,11 @@
22
const SELECTOR_BUTTON = '.headerlink';
33
const SELECTOR_MODAL = '#linkReferenceModal';
44
const SELECTOR_ALERT_RST_NO_ANCHOR = '.alert-permalink-rst';
5+
const SELECTOR_PERMALINK_SHORT_WRAPPER = '.permalink-short-wrapper';
56
const SELECTOR_PERMALINK_URI = '#permalink-uri';
67
const SELECTOR_PERMALINK_SHORT = '#permalink-short';
78
const SELECTOR_PERMALINK_RST = '#permalink-rst';
9+
const SELECTOR_PERMALINK_MD = '#permalink-md';
810
const SELECTOR_PERMALINK_HTML = '#permalink-html';
911
const SELECTOR_ALERT_SUCCESS = '#permalink-alert-success';
1012
const SELECTOR_COPY_BUTTON = '.copy-button';
@@ -37,7 +39,7 @@
3739
function generateRstLink(linkReferenceModal, section, headerText, rstAnchor, filename) {
3840
const interlinkTarget = linkReferenceModal.dataset.interlinkShortcode || 'somemanual';
3941
if (rstAnchor) {
40-
return `:ref:\`${headerText} <${interlinkTarget}:${rstAnchor}>\``;
42+
return `\`${headerText} <https://docs.typo3.org/permalink/${interlinkTarget}:${rstAnchor}>\`_`;
4143
}
4244
if (filename === '') {
4345
return '';
@@ -47,10 +49,13 @@
4749

4850
function showHideRstAnchorAlert(linkReferenceModal, rstAnchor) {
4951
const alertPermalinkRstNoAnchor = linkReferenceModal.querySelector(SELECTOR_ALERT_RST_NO_ANCHOR);
52+
const permalinkShortWrapper = linkReferenceModal.querySelector(SELECTOR_PERMALINK_SHORT_WRAPPER);
5053
if (!rstAnchor) {
5154
alertPermalinkRstNoAnchor.classList.remove('d-none');
55+
permalinkShortWrapper.classList.add('d-none');
5256
} else {
5357
alertPermalinkRstNoAnchor.classList.add('d-none');
58+
permalinkShortWrapper.classList.remove('d-none');
5459
}
5560
}
5661

@@ -62,10 +67,12 @@
6267
// this can happen when opening a local file
6368
linkReferenceModal.querySelector(SELECTOR_PERMALINK_URI).value = '';
6469
linkReferenceModal.querySelector(SELECTOR_PERMALINK_HTML).value = '';
70+
linkReferenceModal.querySelector(SELECTOR_PERMALINK_MD).value = '';
6571
linkReferenceModal.querySelector(SELECTOR_PERMALINK_SHORT).value = '';
6672
} else {
6773
linkReferenceModal.querySelector(SELECTOR_PERMALINK_URI).value = uri;
6874
linkReferenceModal.querySelector(SELECTOR_PERMALINK_SHORT).value = shortUri;
75+
linkReferenceModal.querySelector(SELECTOR_PERMALINK_MD).value = `[${headerText}](${shortUri})`;
6976
linkReferenceModal.querySelector(SELECTOR_PERMALINK_HTML).value = `<a href="${uri}">${headerText}</a>`;
7077
}
7178
const rstInput = linkReferenceModal.querySelector(SELECTOR_PERMALINK_RST);
@@ -126,7 +133,7 @@
126133
const rstLink = rstLinkData ? rstLinkData : generateRstLink(linkReferenceModal, section, headerText, rstAnchor, filename);
127134
const shortUri = generateShortUri(linkReferenceModal, section, headerText, rstAnchor, filename);
128135

129-
updateInputsAndTextareas(linkReferenceModal, header, headerText, uri, rstLink, shortUri);
136+
updateInputsAndTextareas(linkReferenceModal, header, headerText, uri, rstLink, rstAnchor?shortUri:uri);
130137

131138

132139
handleCopyButtons(linkReferenceModal);

‎packages/typo3-docs-theme/resources/config/typo3-docs-theme.php

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@
2121
use T3Docs\Typo3DocsTheme\Compiler\NodeTransformers\CollectPrefixLinkTargetsTransformer;
2222
use T3Docs\Typo3DocsTheme\Compiler\NodeTransformers\ConfvalMenuNodeTransformer;
2323
use T3Docs\Typo3DocsTheme\Compiler\NodeTransformers\RemoveInterlinkSelfReferencesFromCrossReferenceNodeTransformer;
24+
use T3Docs\Typo3DocsTheme\Compiler\NodeTransformers\ReplacePermalinksNodeTransformer;
2425
use T3Docs\Typo3DocsTheme\Directives\ConfvalMenuDirective;
2526
use T3Docs\Typo3DocsTheme\Directives\DirectoryTreeDirective;
2627
use T3Docs\Typo3DocsTheme\Directives\GlossaryDirective;
@@ -83,6 +84,8 @@
8384
->bind('$startingRule', service(DirectiveContentRule::class))
8485
->instanceof(BaseDirective::class)
8586
->tag('phpdoc.guides.directive')
87+
->set(ReplacePermalinksNodeTransformer::class)
88+
->tag('phpdoc.guides.compiler.nodeTransformers')
8689
->set(CollectPrefixLinkTargetsTransformer::class)
8790
->tag('phpdoc.guides.compiler.nodeTransformers')
8891
->set(ConfvalMenuNodeTransformer::class)

‎packages/typo3-docs-theme/resources/public/js/theme.min.js

Lines changed: 6 additions & 6 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎packages/typo3-docs-theme/resources/template/structure/layoutParts/linkReferenceModal.html.twig

Lines changed: 14 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -17,12 +17,14 @@
1717
<input class="form-control code" id="permalink-uri" readonly>
1818
<button type="button" class="btn btn-outline-secondary copy-button" data-target="permalink-uri"><i class="far fa-clone"></i></button>
1919
</div>
20-
<label for="permalink-short" class="col-form-label">Permalink (Shortlink)</label>
21-
<div class="input-group">
22-
<input class="form-control code" id="permalink-short" readonly>
23-
<button type="button" class="btn btn-outline-secondary copy-button" data-target="permalink-short"><i class="far fa-clone"></i></button>
20+
<div class="permalink-short-wrapper">
21+
<label for="permalink-short" class="col-form-label">Permalink (Shortlink)</label>
22+
<div class="input-group">
23+
<input class="form-control code" id="permalink-short" readonly>
24+
<button type="button" class="btn btn-outline-secondary copy-button" data-target="permalink-short"><i class="far fa-clone"></i></button>
25+
</div>
26+
<p><em>Copy and freely share the link</em></p>
2427
</div>
25-
<p><em>Copy and freely share the link</em></p>
2628
</div>
2729
<div class="mb-3">
2830
<div class="alert alert-warning alert-permalink-rst" role="alert">
@@ -39,6 +41,13 @@
3941
</div>
4042
<p><em>Copy this link into your TYPO3 manual.</em></p>
4143
</div>
44+
<div class="mb-3">
45+
<label for="permalink-md" class="col-form-label">Link in Markdown</label>
46+
<div class="input-group">
47+
<textarea class="form-control code" id="permalink-md" readonly></textarea>
48+
<button type="button" class="btn btn-outline-secondary copy-button" data-target="permalink-md"><i class="far fa-clone"></i></button>
49+
</div>
50+
</div>
4251
<div class="mb-3">
4352
<label for="permalink-html" class="col-form-label">Link in HTML</label>
4453
{# @TODO When stable, use the permalink-short in this textarea instead of the "long" URL #}

‎packages/typo3-docs-theme/src/Compiler/NodeTransformers/ReplacePermalinksNodeTransformer.php

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
<?php
2+
3+
declare(strict_types=1);
4+
5+
/**
6+
* This file is part of phpDocumentor.
7+
*
8+
* For the full copyright and license information, please view the LICENSE
9+
* file that was distributed with this source code.
10+
*
11+
* @link https://phpdoc.org
12+
*/
13+
14+
namespace T3Docs\Typo3DocsTheme\Compiler\NodeTransformers;
15+
16+
use phpDocumentor\Guides\Compiler\CompilerContextInterface;
17+
use phpDocumentor\Guides\Compiler\NodeTransformer;
18+
use phpDocumentor\Guides\Nodes\Inline\HyperLinkNode;
19+
use phpDocumentor\Guides\Nodes\Inline\ReferenceNode;
20+
use phpDocumentor\Guides\Nodes\Node;
21+
22+
use function assert;
23+
24+
/** @implements NodeTransformer<HyperLinkNode|ReferenceNode> */
25+
final class ReplacePermalinksNodeTransformer implements NodeTransformer
26+
{
27+
public function __construct(
28+
) {}
29+
30+
public function enterNode(Node $node, CompilerContextInterface $compilerContext): Node
31+
{
32+
return $node;
33+
}
34+
35+
public function leaveNode(Node $node, CompilerContextInterface $compilerContext): Node|null
36+
{
37+
assert($node instanceof HyperLinkNode);
38+
if (!str_starts_with($node->getTargetReference(), 'https://docs.typo3.org/permalink/')) {
39+
return $node;
40+
}
41+
$value = $node->getValue();
42+
if ($value === $node->getTargetReference()) {
43+
$value = '';
44+
}
45+
$url = str_replace('https://docs.typo3.org/permalink/', '', ($node->getTargetReference()));
46+
$version = null;
47+
$interlink = null;
48+
if (str_contains($url, '@')) {
49+
[$url, $version] = explode('@', $url, 2);
50+
}
51+
if (str_contains($url, ':')) {
52+
[$interlink, $url] = explode(':', $url, 2);
53+
}
54+
if ($version !== null && $interlink !== null) {
55+
$interlink = $interlink . '/' . $version;
56+
}
57+
$node = new ReferenceNode($url, $value, $interlink ?? '');
58+
return $node;
59+
}
60+
61+
public function supports(Node $node): bool
62+
{
63+
return $node instanceof HyperLinkNode;
64+
}
65+
66+
public function getPriority(): int
67+
{
68+
return 1000;
69+
}
70+
}

‎tests/Integration/tests-full/breadcrumb/expected/index.html

Lines changed: 14 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -167,12 +167,14 @@ <h5 class="modal-title" id="linkReferenceModalLabel">Reference to the headline</
167167
<input class="form-control code" id="permalink-uri" readonly>
168168
<button type="button" class="btn btn-outline-secondary copy-button" data-target="permalink-uri"><i class="far fa-clone"></i></button>
169169
</div>
170-
<label for="permalink-short" class="col-form-label">Permalink (Shortlink)</label>
171-
<div class="input-group">
172-
<input class="form-control code" id="permalink-short" readonly>
173-
<button type="button" class="btn btn-outline-secondary copy-button" data-target="permalink-short"><i class="far fa-clone"></i></button>
170+
<div class="permalink-short-wrapper">
171+
<label for="permalink-short" class="col-form-label">Permalink (Shortlink)</label>
172+
<div class="input-group">
173+
<input class="form-control code" id="permalink-short" readonly>
174+
<button type="button" class="btn btn-outline-secondary copy-button" data-target="permalink-short"><i class="far fa-clone"></i></button>
175+
</div>
176+
<p><em>Copy and freely share the link</em></p>
174177
</div>
175-
<p><em>Copy and freely share the link</em></p>
176178
</div>
177179
<div class="mb-3">
178180
<div class="alert alert-warning alert-permalink-rst" role="alert">This link target has no permanent anchor assigned.The link below can be used, but is prone to change if the page gets moved.
@@ -184,6 +186,13 @@ <h5 class="modal-title" id="linkReferenceModalLabel">Reference to the headline</
184186
</div>
185187
<p><em>Copy this link into your TYPO3 manual.</em></p>
186188
</div>
189+
<div class="mb-3">
190+
<label for="permalink-md" class="col-form-label">Link in Markdown</label>
191+
<div class="input-group">
192+
<textarea class="form-control code" id="permalink-md" readonly></textarea>
193+
<button type="button" class="btn btn-outline-secondary copy-button" data-target="permalink-md"><i class="far fa-clone"></i></button>
194+
</div>
195+
</div>
187196
<div class="mb-3">
188197
<label for="permalink-html" class="col-form-label">Link in HTML</label>
189198
<div class="input-group">

‎tests/Integration/tests-full/breadcrumb/expected/page.html

Lines changed: 14 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -173,12 +173,14 @@ <h5 class="modal-title" id="linkReferenceModalLabel">Reference to the headline</
173173
<input class="form-control code" id="permalink-uri" readonly>
174174
<button type="button" class="btn btn-outline-secondary copy-button" data-target="permalink-uri"><i class="far fa-clone"></i></button>
175175
</div>
176-
<label for="permalink-short" class="col-form-label">Permalink (Shortlink)</label>
177-
<div class="input-group">
178-
<input class="form-control code" id="permalink-short" readonly>
179-
<button type="button" class="btn btn-outline-secondary copy-button" data-target="permalink-short"><i class="far fa-clone"></i></button>
176+
<div class="permalink-short-wrapper">
177+
<label for="permalink-short" class="col-form-label">Permalink (Shortlink)</label>
178+
<div class="input-group">
179+
<input class="form-control code" id="permalink-short" readonly>
180+
<button type="button" class="btn btn-outline-secondary copy-button" data-target="permalink-short"><i class="far fa-clone"></i></button>
181+
</div>
182+
<p><em>Copy and freely share the link</em></p>
180183
</div>
181-
<p><em>Copy and freely share the link</em></p>
182184
</div>
183185
<div class="mb-3">
184186
<div class="alert alert-warning alert-permalink-rst" role="alert">This link target has no permanent anchor assigned.The link below can be used, but is prone to change if the page gets moved.
@@ -190,6 +192,13 @@ <h5 class="modal-title" id="linkReferenceModalLabel">Reference to the headline</
190192
</div>
191193
<p><em>Copy this link into your TYPO3 manual.</em></p>
192194
</div>
195+
<div class="mb-3">
196+
<label for="permalink-md" class="col-form-label">Link in Markdown</label>
197+
<div class="input-group">
198+
<textarea class="form-control code" id="permalink-md" readonly></textarea>
199+
<button type="button" class="btn btn-outline-secondary copy-button" data-target="permalink-md"><i class="far fa-clone"></i></button>
200+
</div>
201+
</div>
193202
<div class="mb-3">
194203
<label for="permalink-html" class="col-form-label">Link in HTML</label>
195204
<div class="input-group">

‎tests/Integration/tests-full/breadcrumb/expected/yetAnotherPage.html

Lines changed: 14 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -166,12 +166,14 @@ <h5 class="modal-title" id="linkReferenceModalLabel">Reference to the headline</
166166
<input class="form-control code" id="permalink-uri" readonly>
167167
<button type="button" class="btn btn-outline-secondary copy-button" data-target="permalink-uri"><i class="far fa-clone"></i></button>
168168
</div>
169-
<label for="permalink-short" class="col-form-label">Permalink (Shortlink)</label>
170-
<div class="input-group">
171-
<input class="form-control code" id="permalink-short" readonly>
172-
<button type="button" class="btn btn-outline-secondary copy-button" data-target="permalink-short"><i class="far fa-clone"></i></button>
169+
<div class="permalink-short-wrapper">
170+
<label for="permalink-short" class="col-form-label">Permalink (Shortlink)</label>
171+
<div class="input-group">
172+
<input class="form-control code" id="permalink-short" readonly>
173+
<button type="button" class="btn btn-outline-secondary copy-button" data-target="permalink-short"><i class="far fa-clone"></i></button>
174+
</div>
175+
<p><em>Copy and freely share the link</em></p>
173176
</div>
174-
<p><em>Copy and freely share the link</em></p>
175177
</div>
176178
<div class="mb-3">
177179
<div class="alert alert-warning alert-permalink-rst" role="alert">This link target has no permanent anchor assigned.The link below can be used, but is prone to change if the page gets moved.
@@ -183,6 +185,13 @@ <h5 class="modal-title" id="linkReferenceModalLabel">Reference to the headline</
183185
</div>
184186
<p><em>Copy this link into your TYPO3 manual.</em></p>
185187
</div>
188+
<div class="mb-3">
189+
<label for="permalink-md" class="col-form-label">Link in Markdown</label>
190+
<div class="input-group">
191+
<textarea class="form-control code" id="permalink-md" readonly></textarea>
192+
<button type="button" class="btn btn-outline-secondary copy-button" data-target="permalink-md"><i class="far fa-clone"></i></button>
193+
</div>
194+
</div>
186195
<div class="mb-3">
187196
<label for="permalink-html" class="col-form-label">Link in HTML</label>
188197
<div class="input-group">

‎tests/Integration/tests-full/changelog/expected/Changelog/12.0/Breaking-87616-RemovedHookForAlteringPageLinks.html

Lines changed: 14 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -257,12 +257,14 @@ <h5 class="modal-title" id="linkReferenceModalLabel">Reference to the headline</
257257
<input class="form-control code" id="permalink-uri" readonly>
258258
<button type="button" class="btn btn-outline-secondary copy-button" data-target="permalink-uri"><i class="far fa-clone"></i></button>
259259
</div>
260-
<label for="permalink-short" class="col-form-label">Permalink (Shortlink)</label>
261-
<div class="input-group">
262-
<input class="form-control code" id="permalink-short" readonly>
263-
<button type="button" class="btn btn-outline-secondary copy-button" data-target="permalink-short"><i class="far fa-clone"></i></button>
260+
<div class="permalink-short-wrapper">
261+
<label for="permalink-short" class="col-form-label">Permalink (Shortlink)</label>
262+
<div class="input-group">
263+
<input class="form-control code" id="permalink-short" readonly>
264+
<button type="button" class="btn btn-outline-secondary copy-button" data-target="permalink-short"><i class="far fa-clone"></i></button>
265+
</div>
266+
<p><em>Copy and freely share the link</em></p>
264267
</div>
265-
<p><em>Copy and freely share the link</em></p>
266268
</div>
267269
<div class="mb-3">
268270
<div class="alert alert-warning alert-permalink-rst" role="alert">This link target has no permanent anchor assigned. You can make a <a href="https://github.com/typo3/typo3/edit/main/typo3/sysext/core/Documentation/Changelog/12.0/Breaking-87616-RemovedHookForAlteringPageLinks.rst">pull request on GitHub</a> to suggest an anchor.
@@ -275,6 +277,13 @@ <h5 class="modal-title" id="linkReferenceModalLabel">Reference to the headline</
275277
</div>
276278
<p><em>Copy this link into your TYPO3 manual.</em></p>
277279
</div>
280+
<div class="mb-3">
281+
<label for="permalink-md" class="col-form-label">Link in Markdown</label>
282+
<div class="input-group">
283+
<textarea class="form-control code" id="permalink-md" readonly></textarea>
284+
<button type="button" class="btn btn-outline-secondary copy-button" data-target="permalink-md"><i class="far fa-clone"></i></button>
285+
</div>
286+
</div>
278287
<div class="mb-3">
279288
<label for="permalink-html" class="col-form-label">Link in HTML</label>
280289
<div class="input-group">

0 commit comments

Comments
 (0)