Module: GovukTechDocs

Defined in:
lib/govuk_tech_docs/pages.rb,
lib/govuk_tech_docs/version.rb,
lib/govuk_tech_docs/meta_tags.rb,
lib/govuk_tech_docs/redirects.rb,
lib/govuk_tech_docs/page_review.rb,
lib/govuk_tech_docs/path_helpers.rb,
lib/govuk_tech_docs/contribution_banner.rb,
lib/govuk_tech_docs/warning_text_extension.rb,
lib/govuk_tech_docs/tech_docs_html_renderer.rb,
lib/govuk_tech_docs/table_of_contents/heading.rb,
lib/govuk_tech_docs/table_of_contents/helpers.rb,
lib/govuk_tech_docs/unique_identifier_extension.rb,
lib/govuk_tech_docs/unique_identifier_generator.rb,
lib/govuk_tech_docs/custom_method_missing_handler.rb,
lib/govuk_tech_docs/table_of_contents/heading_tree.rb,
lib/govuk_tech_docs/govuk_nunjuck_componenet_renderer.rb,
lib/govuk_tech_docs/table_of_contents/headings_builder.rb,
lib/govuk_tech_docs/api_reference/api_reference_renderer.rb,
lib/govuk_tech_docs/api_reference/api_reference_extension.rb,
lib/govuk_tech_docs/table_of_contents/heading_tree_builder.rb,
lib/govuk_tech_docs/table_of_contents/heading_tree_renderer.rb,
lib/govuk_tech_docs.rb

Defined Under Namespace

Modules: ApiReference, ContributionBanner, PathHelpers, TableOfContents Classes: CustomMethodMissingHandler, GovukNunjuckComponenetRenderer, MetaTags, PageReview, Pages, Redirects, SourceUrls, TechDocsHTMLRenderer, UniqueIdentifierExtension, UniqueIdentifierGenerator, WarningTextExtension

Constant Summary collapse

VERSION = 
"6.1.0".freeze

Class Method Summary collapse

Class Method Details

.configure(context, options = {}) ⇒ Object

Configure the tech docs template

Parameters:

  • options (Hash) (defaults to: {})

Options Hash (options):

  • livereload (Hash) —

    Options to pass to the ‘livereload` extension. Hash with symbols as keys.



48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
 
# File 'lib/govuk_tech_docs.rb', line 48

def self.configure(context, options = {})
  context.activate :sprockets

  context.sprockets.append_path File.join(__dir__, "../node_modules/govuk-frontend/dist")
  context.sprockets.append_path File.join(__dir__, "./source")

  context.activate :syntax

  context.files.watch :source, path: "#{__dir__}/source"

  context.set :markdown_engine, :redcarpet
  context.set :markdown,
              renderer: TechDocsHTMLRenderer.new(
                with_toc_data: true,
                api: true,
                context:,
              ),
              fenced_code_blocks: true,
              tables: true,
              no_intra_emphasis: true

  # this doesnt seem to work
  context.set :sass, { output_style: "nested", quiet_deps: true }

  # Reload the browser automatically whenever files change
  context.configure :development do
    activate :livereload, options[:livereload].to_h
  end

  context.configure :build do
    activate :autoprefixer
    activate :minify_javascript, compressor: Terser.new, ignore: ["/raw_assets/*"]
  end

  config_file = ENV.fetch("CONFIG_FILE", "config/tech-docs.yml")
  context.config[:tech_docs] = YAML.load_file(config_file).with_indifferent_access
  context.activate :unique_identifier
  context.activate :warning_text
  context.activate :api_reference

  context.helpers do
    include GovukTechDocs::PathHelpers
    include GovukTechDocs::TableOfContents::Helpers
    include GovukTechDocs::ContributionBanner

    def meta_tags
      @meta_tags ||= GovukTechDocs::MetaTags.new(config, current_page)
    end

    def current_page_review
      @current_page_review ||= GovukTechDocs::PageReview.new(current_page, config)
    end

    def format_date(date)
      date.strftime("%-e %B %Y")
    end

    def active_page(page_path)
      # if we are on the homepage e.g  Documentation: /
      if page_path == "/" && current_page.url == "/"
        return true
      end

      # if we are on a single page the header links point to e.g Expired page: /expired-page.html
      if "/#{current_page.path}" == page_path
        return true
      end

      # If the doc maintainer has set the parent data in the frontmatter for the current page,
      # and it matches the value in the config e.g
      # Expired page: /expired-page.html (config) and parent: /expired-page.html (child-of-expired-page.html)
      if !current_page.data.parent.nil? && current_page.data.parent.to_s == page_path
        return true
      end

      # If we have a nested directory structure that matches a navigation link e.g  Active pages: /active-pages/
      if current_page.url.start_with?(page_path)
        # feels like a weird check, but stops false positive where "/" for root is also the start of "/active-pages"
        if page_path == "/"
          return current_page.url == "/"
        end

        # safe to return true, since we aren't in the situation above
        return true
      end
      # no other reason to believe we're active
      false
    end
  end

  context.page "/*.xml", layout: false
  context.page "/*.json", layout: false
  context.page "/*.txt", layout: false

  context.ready do
    redirects = GovukTechDocs::Redirects.new(context).redirects

    redirects.each do |from, to|
      context.redirect from, to
    end
  end

  if context.config[:tech_docs][:enable_search]
    context.activate :search do |search|
      search.resources = [""]

      search.fields = {
        title: { boost: 100, store: true, required: true },
        content: { boost: 50, store: true },
        url: { index: false, store: true },
      }

      search.pipeline_remove = %w[stemmer stopWordFilter]

      search.tokenizer_separator = '/[\s\-/]+/'
    end
  else
    context.ignore "search/*"
  end

  if context.config[:tech_docs][:enable_govuk_components]
    context.activate :custom_method_missing_handler
  end
end