Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Allow additional markdown options #170

Closed
wants to merge 3 commits into from
Closed

Allow additional markdown options #170

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
1b97fac
Allow markdown renderer options to be overriden.
NickColley Feb 24, 2020
11fba6a
Add indented code block example
NickColley Feb 24, 2020
308795a
Use config.yml to configure markdown options
NickColley Feb 24, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,11 @@

## Unreleased

### Fixes
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this was accidentally added...


- [Pull request #162: Fix line height spacing for multiline code elements](https://github.com/alphagov/tech-docs-gem/pull/162)
- [Pull request #165: Update header alignment to match layout](https://github.com/alphagov/tech-docs-gem/pull/165)

## 2.0.11

### Fixes
Expand Down
4 changes: 4 additions & 0 deletions example/config/tech-docs.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -52,3 +52,7 @@ api_path: source/pets.yml
# Optional global settings for the page review process
owner_slack_workspace: gds
default_owner_slack: '#2nd-line'

# Markdown options
markdown:
disable_indented_code_blocks: true
11 changes: 8 additions & 3 deletions example/source/code.html.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ A paragraph with a `code` element within it.

<a href="#"><code>code element within a link</code></a>

An example of a table with a `code` element within it.
## Table with a `code` element within it.

<div class="table-container">
<table>
Expand Down Expand Up @@ -37,7 +37,7 @@ An example of a table with a `code` element within it.
</table>
</div>

An example of a code block with a long line length
## Code block with a long line length

```ruby
RSpec.describe ContentItem do
Expand All @@ -56,9 +56,14 @@ RSpec.describe ContentItem do
end
```

An example of a code block with a short length
## Fenced code block with a short length

```ruby
RSpec.describe ContentItem do
end
```

## Indented code block

RSpec.describe ContentItem do
end
27 changes: 16 additions & 11 deletions lib/govuk_tech_docs.rb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,9 @@ module GovukTechDocs
# @option options [Hash] livereload Options to pass to the `livereload`
# extension. Hash with symbols as keys.
def self.configure(context, options = {})
config_file = ENV.fetch("CONFIG_FILE", "config/tech-docs.yml")
context.config[:tech_docs] = YAML.load_file(config_file).with_indifferent_access

context.activate :sprockets

context.sprockets.append_path File.join(__dir__, "../node_modules/govuk-frontend/")
Expand All @@ -40,15 +43,19 @@ def self.configure(context, options = {})
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: context,
),
fenced_code_blocks: true,
tables: true,
no_intra_emphasis: true

default_markdown_options = {
renderer: TechDocsHTMLRenderer.new(
with_toc_data: true,
api: true,
context: context,
),
fenced_code_blocks: true,
tables: true,
no_intra_emphasis: true
}
markdown_options = context.config[:tech_docs][:markdown].transform_keys(&:to_sym) || {}
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What happens if there are no markdown options specified in the config file? Does this need to be guarded?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I believe It'll return falsy and the {} will be used.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Doesn't seem to like the chaining when I try it:

irb(main):004:0> foo = { :tech_docs => { :something => true }}
=> {:tech_docs=>{:something=>true}}
irb(main):005:0> foo[:tech_docs][:markdown].transform_keys(&:to_sym) || {}
Traceback (most recent call last):
        4: from /Users/oliverbyford/.rbenv/versions/2.6.3/bin/irb:23:in `<main>'
        3: from /Users/oliverbyford/.rbenv/versions/2.6.3/bin/irb:23:in `load'
        2: from /Users/oliverbyford/.rbenv/versions/2.6.3/lib/ruby/gems/2.6.0/gems/irb-1.0.0/exe/irb:11:in `<top (required)>'
        1: from (irb):5
NoMethodError (undefined method `transform_keys' for nil:NilClass)

Looks like it works OK with safe navigation (&.) though:

irb(main):004:0> foo = { :tech_docs => { :something => true }}
=> {:tech_docs=>{:something=>true}}
irb(main):006:0> foo[:tech_docs][:markdown]&.transform_keys(&:to_sym) || {}
=> {}
irb(main):007:0> foo = { :tech_docs => { :something => true, :markdown => { :be_awesome => true }}}
=> {:tech_docs=>{:something=>true, :markdown=>{:be_awesome=>true}}}
irb(main):008:0> foo[:tech_docs][:markdown]&.transform_keys(&:to_sym) || {}
=> {:be_awesome=>true}

context.set :markdown, default_markdown_options.merge(markdown_options)

# Reload the browser automatically whenever files change
context.configure :development do
Expand All @@ -60,8 +67,6 @@ def self.configure(context, options = {})
activate :minify_javascript, 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
Expand Down