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.mdindex 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 theAvoid 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.+## ContributingWhen 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.mdindex 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.rbindex 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_docsattr_reader :remote_contentdef initialize(**kwargs)@@ -59,6 +66,8 @@ class LocalDocunused_assets.each { |asset| assets.delete(asset) }+ result = with_doc_links(result)+result = <<~MD#{result}@@ -79,6 +88,10 @@ class LocalDocendend+ def broken_doc_links+ content.scan(DOC_LINK_REGEX).flatten.reject { |target| linked_doc(target) }+ end+def serialized_assetsJSON.pretty_generate(assets.map do |asset|@@ -105,4 +118,19 @@ class LocalDoc@remote_content = valueend++ 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 }+ endenddiff --git a/docs/developer-guides/sync_docs b/docs/developer-guides/sync_docsindex 8ae025d9ee7..140989e1422 100755--- a/docs/developer-guides/sync_docs+++ b/docs/developer-guides/sync_docs@@ -41,6 +41,8 @@ Dirdocs.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 @@ docsendend+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_KEYputs "Fetching remote info via data-explorer..."