Skip to content

A platform for community discussion. Free, open, simple.

FIX: Rewrite relative doc links to topic links when syncing to meta (#43532)

Kris2d18e14bb073
diff --git a/docs/developer-guides/README.md b/docs/developer-guides/README.md
index cbeba8c1372..7a79ebfd3dd 100644
--- a/docs/developer-guides/README.md
+++ b/docs/developer-guides/README.md
@@ -72,6 +72,16 @@ The sync tool will automatically upload the images to Discourse, and replace the
Avoid hotlinking images from other sources. If you do, Discourse may download them and update the topic content. This will cause the docs sync tool to detect a diff, and update the topic unnecessarily.
+## Links between docs
+
+Link to other docs using a relative path to their markdown file, so the link works when browsing the repository. For example:
+
+```
+See the [DModal API](12-dmodal-api.md) or [theme settings](../05-themes-components/09-theme-settings.md).
+```
+
+The sync tool rewrites these to the corresponding Discourse topic. Heading fragments (`#some-heading`) are dropped, becasue Discourse anchors are generated differently. Relative links to files which aren't docs will fail validation.
+
## Contributing
When working on substantial changes, you may like to set up a staging environment to preview your changes.
diff --git a/docs/developer-guides/docs/05-themes-components/02-quick-reference.md b/docs/developer-guides/docs/05-themes-components/02-quick-reference.md
index 38b29a4d2b6..cb6ab04a812 100644
--- a/docs/developer-guides/docs/05-themes-components/02-quick-reference.md
+++ b/docs/developer-guides/docs/05-themes-components/02-quick-reference.md
@@ -13,8 +13,8 @@ As themes grow more powerful, there's more to remember about how they work. We h
[:scroll: Developer's guide](https://meta.discourse.org/t/developer-s-guide-to-discourse-themes/93648)
[:paintbrush: Theme Creator](http://theme-creator.discourse.org)
[:desktop_computer: Theme CLI](https://meta.discourse.org/t/discourse-theme-cli-console-app-to-help-you-build-themes/82950)
-[:notebook_with_decorative_cover: Theme Directory](/c/customization/theme/61/none)
-[:jigsaw: Component Directory](/c/customization/theme-component/120)
+[:notebook_with_decorative_cover: Theme Directory](https://meta.discourse.org/c/customization/theme/61/none)
+[:jigsaw: Component Directory](https://meta.discourse.org/c/customization/theme-component/120)
[:wrench: Theme Modifiers](https://meta.discourse.org/t/theme-modifiers-a-brief-introduction/150605)
[:wrench: Themeable site settings](https://meta.discourse.org/t/-/374376)
diff --git a/docs/developer-guides/lib/local_doc.rb b/docs/developer-guides/lib/local_doc.rb
index a718ef4c0f4..5127dea7ae8 100644
--- a/docs/developer-guides/lib/local_doc.rb
+++ b/docs/developer-guides/lib/local_doc.rb
@@ -3,6 +3,12 @@
Asset = Struct.new(:local_path, :local_sha1, :remote_short_url, keyword_init: true)
class LocalDoc
+ DOCS_DIR = File.expand_path("#{__dir__}/../docs")
+
+ # Relative links to other docs, e.g. `[DModal](12-dmodal-api.md#usage)`. Captures the path only;
+ # fragments are dropped on sync because Discourse heading anchors include the post id.
+ DOC_LINK_REGEX = %r{\]\((?![a-z][a-z0-9+.-]*:|/)([^)\s#]+\.md)(?:#[^)\s]*)?\)}i
+
attr_accessor :path,
:frontmatter,
:content,
@@ -10,7 +16,8 @@ class LocalDoc
:first_post_id,
:remote_title,
:remote_deleted,
- :assets
+ :assets,
+ :all_docs
attr_reader :remote_content
def initialize(**kwargs)
@@ -59,6 +66,8 @@ class LocalDoc
unused_assets.each { |asset| assets.delete(asset) }
+ result = with_doc_links(result)
+
result = <<~MD
#{result}
@@ -79,6 +88,10 @@ class LocalDoc
end
end
+ def broken_doc_links
+ content.scan(DOC_LINK_REGEX).flatten.reject { |target| linked_doc(target) }
+ end
+
def serialized_assets
JSON.pretty_generate(
assets.map do |asset|
@@ -105,4 +118,19 @@ class LocalDoc
@remote_content = value
end
+
+ private
+
+ def with_doc_links(text)
+ text.gsub(DOC_LINK_REGEX) do |match|
+ # A linked doc created in this run has no topic yet; the update pass fills it in.
+ linked_topic_id = linked_doc($1)&.topic_id
+ linked_topic_id ? "](/t/-/#{linked_topic_id})" : match
+ end
+ end
+
+ def linked_doc(target)
+ resolved = File.expand_path(target, File.dirname(File.join(DOCS_DIR, path)))
+ all_docs.find { |doc| File.join(DOCS_DIR, doc.path) == resolved }
+ end
end
diff --git a/docs/developer-guides/sync_docs b/docs/developer-guides/sync_docs
index 8ae025d9ee7..140989e1422 100755
--- a/docs/developer-guides/sync_docs
+++ b/docs/developer-guides/sync_docs
@@ -41,6 +41,8 @@ Dir
docs.push(LocalDoc.new(frontmatter:, path:, content:))
end
+docs.each { |doc| doc.all_docs = docs }
+
puts "Validating local docs..."
docs
.group_by { |doc| doc.external_id }
@@ -52,6 +54,13 @@ docs
end
end
+broken_links = docs.flat_map { |doc| doc.broken_doc_links.map { |target| [doc.path, target] } }
+if broken_links.any?
+ puts "- links to unknown docs found:"
+ broken_links.each { |path, target| puts "- '#{target}' in #{path}" }
+ exit 1
+end
+
exit 0 if !DOCS_API_KEY
puts "Fetching remote info via data-explorer..."