Skip to content

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

3.8 KB
Raw Blame
# frozen_string_literal: true

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

  # Markdown images, e.g. `![alt](/assets/image.png)`. Captures the path.
  IMAGE_REGEX = /![^\]]+\]\(([^)]+)\)/

  attr_accessor :path,
                :frontmatter,
                :content,
                :topic_id,
                :first_post_id,
                :remote_title,
                :remote_deleted,
                :assets,
                :all_docs
  attr_reader :remote_content

  def initialize(**kwargs)
    kwargs.each { |k, v| send("#{k}=", v) }
    self.assets ||= []
  end

  def external_id
    "DOC-#{frontmatter["id"]}"
  end

  def section
    path_segments = path.split("/")
    path_segments[0] if path_segments.size > 1
  end

  def content_with_uploads
    unused_assets = assets.dup

    result =
      content.gsub(IMAGE_REGEX) do |match|
        path = $1
        next match if !path.start_with?("/")

        resolved = File.expand_path("#{__dir__}/../#{path}")
        assets_dir = File.expand_path("#{__dir__}/../assets/")
        raise "Invalid path: #{resolved}" if !resolved.start_with?(assets_dir)

        digest = Digest::SHA1.file(resolved).hexdigest

        asset = assets.find { |a| a.local_sha1 == digest }
        unused_assets.delete(asset)
        if !asset
          puts "  Uploading #{path}..."
          result = API.upload_file(resolved)
          raise "File upload failed: #{result.inspect}" if !result["short_url"]
          asset =
            Asset.new(local_path: path, local_sha1: digest, remote_short_url: result["short_url"])
          assets.push(asset)
        end

        short_url = asset.remote_short_url

        match.gsub(path, short_url)
      end

    unused_assets.each { |asset| assets.delete(asset) }

    result = with_doc_links(result)

    result = <<~MD
      #{result}

      ---

      <small>This document is version controlled - suggest changes [on github](https://github.com/discourse/discourse/blob/main/docs/developer-guides/docs/#{path}).</small>
    MD

    if assets.size == 0
      result
    else
      <<~MD
        #{result}
        <!-- START DOCS ASSET MAP
        #{serialized_assets}
        END DOCS ASSET MAP -->
      MD
    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|
        {
          local_path: asset.local_path,
          local_sha1: asset.local_sha1,
          remote_short_url: asset.remote_short_url,
        }
      end,
    )
  end

  def remote_content=(value)
    if value.match(/<!-- START DOCS ASSET MAP\n(.+?)\nEND DOCS ASSET MAP -->/m)
      self.assets = JSON.parse($1).map { |raw_asset| Asset.new(**raw_asset) }
    end

    value.gsub!(/![^\]]+\]\(([^)]+)\)/) do |match|
      url = $1
      found_asset = assets.find { |a| a.remote_short_url == url }
      match.sub!(path, found_asset.local_path) if found_asset
      match
    end

    @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