Automatic merge of gitlab-org/gitlab-ce master

changelogs/unreleased/64070-asciidoctor-enable-section-anchors.yml

+---
+title: "Enable section anchors in Asciidoctor"
+merge_request: 30666
+author: Guillaume Grossetie
+type: added
\ No newline at end of file

doc/api/releases/index.md

@@ -6,7 +6,7 @@
 
 ## List Releases
 
-Paginated list of Releases, sorted by `created_at`.
+Paginated list of Releases, sorted by `released_at`.
 
 ```
 GET /projects/:id/releases
@@ -32,6 +32,7 @@ Example response:
       "name":"Awesome app v0.2 beta",
       "description_html":"\u003ch2 dir=\"auto\"\u003e\n\u003ca id=\"user-content-changelog\" class=\"anchor\" href=\"#changelog\" aria-hidden=\"true\"\u003e\u003c/a\u003eCHANGELOG\u003c/h2\u003e\n\u003cul dir=\"auto\"\u003e\n\u003cli\u003eEscape label and milestone titles to prevent XSS in GFM autocomplete. !2740\u003c/li\u003e\n\u003cli\u003ePrevent private snippets from being embeddable.\u003c/li\u003e\n\u003cli\u003eAdd subresources removal to member destroy service.\u003c/li\u003e\n\u003c/ul\u003e",
       "created_at":"2019-01-03T01:56:19.539Z",
+      "released_at":"2019-01-03T01:56:19.539Z",
       "author":{
          "id":1,
          "name":"Administrator",
@@ -98,6 +99,7 @@ Example response:
       "name":"Awesome app v0.1 alpha",
       "description_html":"\u003ch2 dir=\"auto\"\u003e\n\u003ca id=\"user-content-changelog\" class=\"anchor\" href=\"#changelog\" aria-hidden=\"true\"\u003e\u003c/a\u003eCHANGELOG\u003c/h2\u003e\n\u003cul dir=\"auto\"\u003e\n\u003cli\u003eRemove limit of 100 when searching repository code. !8671\u003c/li\u003e\n\u003cli\u003eShow error message when attempting to reopen an MR and there is an open MR for the same branch. !16447 (Akos Gyimesi)\u003c/li\u003e\n\u003cli\u003eFix a bug where internal email pattern wasn't respected. !22516\u003c/li\u003e\n\u003c/ul\u003e",
       "created_at":"2019-01-03T01:55:18.203Z",
+      "released_at":"2019-01-03T01:55:18.203Z",
       "author":{
          "id":1,
          "name":"Administrator",
@@ -178,6 +180,7 @@ Example response:
    "name":"Awesome app v0.1 alpha",
    "description_html":"\u003ch2 dir=\"auto\"\u003e\n\u003ca id=\"user-content-changelog\" class=\"anchor\" href=\"#changelog\" aria-hidden=\"true\"\u003e\u003c/a\u003eCHANGELOG\u003c/h2\u003e\n\u003cul dir=\"auto\"\u003e\n\u003cli\u003eRemove limit of 100 when searching repository code. !8671\u003c/li\u003e\n\u003cli\u003eShow error message when attempting to reopen an MR and there is an open MR for the same branch. !16447 (Akos Gyimesi)\u003c/li\u003e\n\u003cli\u003eFix a bug where internal email pattern wasn't respected. !22516\u003c/li\u003e\n\u003c/ul\u003e",
    "created_at":"2019-01-03T01:55:18.203Z",
+   "released_at":"2019-01-03T01:55:18.203Z",
    "author":{
       "id":1,
       "name":"Administrator",
@@ -247,6 +250,7 @@ POST /projects/:id/releases
 | `assets:links`| array of hash  | no       | An array of assets links.               |
 | `assets:links:name`| string    | no (if `assets:links` specified, it's required)    | The name of the link. |
 | `assets:links:url`| string    | no (if `assets:links` specified, it's required)    | The url of the link. |
+| `released_at` | datetime       | no       | The date when the release will be/was ready. Defaults to the current time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). |
 
 Example request:
 
@@ -265,6 +269,7 @@ Example response:
    "name":"New release",
    "description_html":"\u003cp dir=\"auto\"\u003eSuper nice release\u003c/p\u003e",
    "created_at":"2019-01-03T02:22:45.118Z",
+   "released_at":"2019-01-03T02:22:45.118Z",
    "author":{
       "id":1,
       "name":"Administrator",
@@ -335,6 +340,7 @@ PUT /projects/:id/releases/:tag_name
 | `tag_name`    | string         | yes      | The tag where the release will be created from. |
 | `name`        | string         | no       | The release name.                       |
 | `description` | string         | no       | The description of the release. You can use [markdown](../../user/markdown.md). |
+| `released_at` | datetime       | no       | The date when the release will be/was ready. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). |
 
 Example request:
 
@@ -351,6 +357,7 @@ Example response:
    "name":"new name",
    "description_html":"\u003ch2 dir=\"auto\"\u003e\n\u003ca id=\"user-content-changelog\" class=\"anchor\" href=\"#changelog\" aria-hidden=\"true\"\u003e\u003c/a\u003eCHANGELOG\u003c/h2\u003e\n\u003cul dir=\"auto\"\u003e\n\u003cli\u003eRemove limit of 100 when searching repository code. !8671\u003c/li\u003e\n\u003cli\u003eShow error message when attempting to reopen an MR and there is an open MR for the same branch. !16447 (Akos Gyimesi)\u003c/li\u003e\n\u003cli\u003eFix a bug where internal email pattern wasn't respected. !22516\u003c/li\u003e\n\u003c/ul\u003e",
    "created_at":"2019-01-03T01:55:18.203Z",
+   "released_at":"2019-01-03T01:55:18.203Z",
    "author":{
       "id":1,
       "name":"Administrator",
@@ -430,6 +437,7 @@ Example response:
    "name":"new name",
    "description_html":"\u003ch2 dir=\"auto\"\u003e\n\u003ca id=\"user-content-changelog\" class=\"anchor\" href=\"#changelog\" aria-hidden=\"true\"\u003e\u003c/a\u003eCHANGELOG\u003c/h2\u003e\n\u003cul dir=\"auto\"\u003e\n\u003cli\u003eRemove limit of 100 when searching repository code. !8671\u003c/li\u003e\n\u003cli\u003eShow error message when attempting to reopen an MR and there is an open MR for the same branch. !16447 (Akos Gyimesi)\u003c/li\u003e\n\u003cli\u003eFix a bug where internal email pattern wasn't respected. !22516\u003c/li\u003e\n\u003c/ul\u003e",
    "created_at":"2019-01-03T01:55:18.203Z",
+   "released_at":"2019-01-03T01:55:18.203Z",
    "author":{
       "id":1,
       "name":"Administrator",
@@ -480,3 +488,11 @@ Example response:
    }
 }
 ```
+
+## Upcoming Releases
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/38105) in GitLab 12.1.
+
+A release with a `released_at` attribute set to a future date will be labeled an **Upcoming Release** in the UI:
+
+![Upcoming release](img/upcoming_release_v12_1.png)

lib/api/releases.rb

@@ -78,7 +78,7 @@ module API
         requires :tag_name,    type: String, desc: 'The name of the tag', as: :tag
         optional :name,        type: String, desc: 'The name of the release'
         optional :description, type: String, desc: 'Release notes with markdown support'
-        optional :released_at, type: DateTime, desc: 'The date when the release will be/was ready. Defaults to the current time.'
+        optional :released_at, type: DateTime, desc: 'The date when the release will be/was ready.'
       end
       put ':id/releases/:tag_name', requirements: RELEASE_ENDPOINT_REQUIREMETS do
         authorize_update_release!

lib/banzai/filter/ascii_doc_sanitization_filter.rb

@@ -6,6 +6,9 @@ module Banzai
     #
     # Extends Banzai::Filter::BaseSanitizationFilter with specific rules.
     class AsciiDocSanitizationFilter < Banzai::Filter::BaseSanitizationFilter
+      # Section anchor link pattern
+      SECTION_LINK_REF_PATTERN = /\A#{Gitlab::Asciidoc::DEFAULT_ADOC_ATTRS['idprefix']}(:?[[:alnum:]]|-|_)+\z/.freeze
+
       # Classes used by Asciidoctor to style components
       ADMONITION_CLASSES = %w(fa icon-note icon-tip icon-warning icon-caution icon-important).freeze
       CALLOUT_CLASSES = ['conum'].freeze
@@ -19,14 +22,17 @@ module Banzai
         td: ['icon'].freeze,
         i: ADMONITION_CLASSES + CALLOUT_CLASSES + CHECKLIST_CLASSES,
         ul: LIST_CLASSES,
-        ol: LIST_CLASSES
+        ol: LIST_CLASSES,
+        a: ['anchor'].freeze
       }.freeze
 
+      ALLOWED_HEADERS = %w(h2 h3 h4 h5 h6).freeze
+
       def customize_whitelist(whitelist)
         # Allow marks
         whitelist[:elements].push('mark')
 
-        # Allow any classes in `span`, `i`, `div`, `td`, `ul` and `ol` elements
+        # Allow any classes in `span`, `i`, `div`, `td`, `ul`, `ol` and `a` elements
         # but then remove any unknown classes
         whitelist[:attributes]['span'] = %w(class)
         whitelist[:attributes]['div'].push('class')
@@ -34,12 +40,32 @@ module Banzai
         whitelist[:attributes]['i'] = %w(class)
         whitelist[:attributes]['ul'] = %w(class)
         whitelist[:attributes]['ol'] = %w(class)
+        whitelist[:attributes]['a'].push('class')
         whitelist[:transformers].push(self.class.remove_element_classes)
 
+        # Allow `id` in heading elements for section anchors
+        ALLOWED_HEADERS.each do |header|
+          whitelist[:attributes][header] = %w(id)
+        end
+        whitelist[:transformers].push(self.class.remove_non_heading_ids)
+
         whitelist
       end
 
       class << self
+        def remove_non_heading_ids
+          lambda do |env|
+            node = env[:node]
+
+            return unless ALLOWED_HEADERS.any?(node.name)
+            return unless node.has_attribute?('id')
+
+            return if node['id'] =~ SECTION_LINK_REF_PATTERN
+
+            node.remove_attribute('id')
+          end
+        end
+
         def remove_element_classes
           lambda do |env|
             node = env[:node]

lib/gitlab/asciidoc.rb

@@ -13,6 +13,7 @@ module Gitlab
     MAX_INCLUDE_DEPTH = 5
     DEFAULT_ADOC_ATTRS = {
         'showtitle' => true,
+        'sectanchors' => true,
         'idprefix' => 'user-content-',
         'idseparator' => '-',
         'env' => 'gitlab',

spec/lib/gitlab/asciidoc_spec.rb

@@ -96,6 +96,75 @@ module Gitlab
         end
       end
 
+      context 'with passthrough' do
+        it 'removes non heading ids' do
+          input = <<~ADOC
+            ++++
+            <h2 id="foo">Title</h2>
+            ++++
+          ADOC
+
+          output = <<~HTML
+           <h2>Title</h2>
+          HTML
+
+          expect(render(input, context)).to include(output.strip)
+        end
+      end
+
+      context 'with section anchors' do
+        it 'preserves ids and links' do
+          input = <<~ADOC
+            = Title
+
+            == First section
+
+            This is the first section.
+
+            == Second section
+
+            This is the second section.
+
+            == Thunder ⚡ !
+
+            This is the third section.
+          ADOC
+
+          output = <<~HTML
+           <h1>Title</h1>
+           <div>
+           <h2 id="user-content-first-section">
+           <a class="anchor" href="#user-content-first-section"></a>First section</h2>
+           <div>
+           <div>
+           <p>This is the first section.</p>
+           </div>
+           </div>
+           </div>
+           <div>
+           <h2 id="user-content-second-section">
+           <a class="anchor" href="#user-content-second-section"></a>Second section</h2>
+           <div>
+           <div>
+           <p>This is the second section.</p>
+           </div>
+           </div>
+           </div>
+           <div>
+           <h2 id="user-content-thunder">
+           <a class="anchor" href="#user-content-thunder"></a>Thunder ⚡ !</h2>
+           <div>
+           <div>
+           <p>This is the third section.</p>
+           </div>
+           </div>
+           </div>
+          HTML
+
+          expect(render(input, context)).to include(output.strip)
+        end
+      end
+
       context 'with checklist' do
         it 'preserves classes' do
           input = <<~ADOC