+
+
+ {{ $options.i18n.CLEANUP_STATUS_UNFINISHED }}
+
+
+ {{ calculatedTimeTilNextRun }}{{
+ content
+ }}
+
+
diff --git a/app/assets/javascripts/packages_and_registries/container_registry/explorer/components/list_page/image_list.vue b/app/assets/javascripts/packages_and_registries/container_registry/explorer/components/list_page/image_list.vue
index 5bd13322ebb..6f1f67e251f 100644
--- a/app/assets/javascripts/packages_and_registries/container_registry/explorer/components/list_page/image_list.vue
+++ b/app/assets/javascripts/packages_and_registries/container_registry/explorer/components/list_page/image_list.vue
@@ -22,6 +22,11 @@ export default {
type: Object,
required: true,
},
+ expirationPolicy: {
+ type: Object,
+ default: () => ({}),
+ required: false,
+ },
},
computed: {
showPagination() {
@@ -38,6 +43,7 @@ export default {
:key="index"
:item="listItem"
:metadata-loading="metadataLoading"
+ :expiration-policy="expirationPolicy"
@delete="$emit('delete', $event)"
/>
+
{{ statusText }}
diff --git a/app/assets/javascripts/packages_and_registries/container_registry/explorer/components/list_page/image_list_row.vue b/app/assets/javascripts/packages_and_registries/container_registry/explorer/components/list_page/image_list_row.vue
index 484903354e8..12263c6fc5a 100644
--- a/app/assets/javascripts/packages_and_registries/container_registry/explorer/components/list_page/image_list_row.vue
+++ b/app/assets/javascripts/packages_and_registries/container_registry/explorer/components/list_page/image_list_row.vue
@@ -6,12 +6,10 @@ import { n__ } from '~/locale';
import ClipboardButton from '~/vue_shared/components/clipboard_button.vue';
import ListItem from '~/vue_shared/components/registry/list_item.vue';
import {
- ASYNC_DELETE_IMAGE_ERROR_MESSAGE,
LIST_DELETE_BUTTON_DISABLED,
LIST_DELETE_BUTTON_DISABLED_FOR_MIGRATION,
REMOVE_REPOSITORY_LABEL,
ROW_SCHEDULED_FOR_DELETION,
- CLEANUP_TIMED_OUT_ERROR_MESSAGE,
IMAGE_DELETE_SCHEDULED_STATUS,
IMAGE_FAILED_DELETED_STATUS,
IMAGE_MIGRATING_STATE,
@@ -45,6 +43,11 @@ export default {
default: false,
required: false,
},
+ expirationPolicy: {
+ type: Object,
+ default: () => ({}),
+ required: false,
+ },
},
i18n: {
REMOVE_REPOSITORY_LABEL,
@@ -73,15 +76,6 @@ export default {
this.item.tagsCount,
);
},
- warningIconText() {
- if (this.failedDelete) {
- return ASYNC_DELETE_IMAGE_ERROR_MESSAGE;
- }
- if (this.item.expirationPolicyStartedAt) {
- return CLEANUP_TIMED_OUT_ERROR_MESSAGE;
- }
- return null;
- },
imageName() {
return this.item.name ? this.item.path : `${this.item.path}/ ${ROOT_IMAGE_TEXT}`;
},
@@ -140,6 +134,7 @@ export default {
v-if="item.expirationPolicyCleanupStatus"
class="ml-2"
:status="item.expirationPolicyCleanupStatus"
+ :expiration-policy-next-run-at="expirationPolicy.next_run_at"
/>
diff --git a/app/assets/javascripts/packages_and_registries/container_registry/explorer/constants/details.js b/app/assets/javascripts/packages_and_registries/container_registry/explorer/constants/details.js
index 3c7f7ca9aa8..2a58933cd64 100644
--- a/app/assets/javascripts/packages_and_registries/container_registry/explorer/constants/details.js
+++ b/app/assets/javascripts/packages_and_registries/container_registry/explorer/constants/details.js
@@ -87,7 +87,7 @@ export const CLEANUP_DISABLED_TOOLTIP = s__(
export const CLEANUP_STATUS_SCHEDULED = s__('ContainerRegistry|Cleanup will run soon');
export const CLEANUP_STATUS_ONGOING = s__('ContainerRegistry|Cleanup is ongoing');
-export const CLEANUP_STATUS_UNFINISHED = s__('ContainerRegistry|Cleanup timed out');
+export const CLEANUP_STATUS_UNFINISHED = s__('ContainerRegistry|Partial cleanup complete');
export const DETAILS_DELETE_IMAGE_ERROR_MESSAGE = s__(
'ContainerRegistry|Something went wrong while scheduling the image for deletion.',
diff --git a/app/assets/javascripts/packages_and_registries/container_registry/explorer/constants/expiration_policies.js b/app/assets/javascripts/packages_and_registries/container_registry/explorer/constants/expiration_policies.js
index e584da23edb..9d0ecfd2dcb 100644
--- a/app/assets/javascripts/packages_and_registries/container_registry/explorer/constants/expiration_policies.js
+++ b/app/assets/javascripts/packages_and_registries/container_registry/explorer/constants/expiration_policies.js
@@ -10,7 +10,7 @@ export const DELETE_ALERT_TITLE = s__('ContainerRegistry|Some tags were not dele
export const DELETE_ALERT_LINK_TEXT = s__(
'ContainerRegistry|The cleanup policy timed out before it could delete all tags. An administrator can %{adminLinkStart}manually run cleanup now%{adminLinkEnd} or you can wait for the cleanup policy to automatically run again. %{docLinkStart}More information%{docLinkEnd}',
);
-export const CLEANUP_TIMED_OUT_ERROR_MESSAGE = s__(
- 'ContainerRegistry|Cleanup timed out before it could delete all tags',
+export const PARTIAL_CLEANUP_CONTINUE_MESSAGE = s__(
+ 'ContainerRegistry|The cleanup will continue within %{time}. %{linkStart}Learn more%{linkEnd}',
);
export const SET_UP_CLEANUP = s__('ContainerRegistry|Set up cleanup');
diff --git a/app/assets/javascripts/packages_and_registries/container_registry/explorer/pages/list.vue b/app/assets/javascripts/packages_and_registries/container_registry/explorer/pages/list.vue
index bb116d5f842..c1bd71de646 100644
--- a/app/assets/javascripts/packages_and_registries/container_registry/explorer/pages/list.vue
+++ b/app/assets/javascripts/packages_and_registries/container_registry/explorer/pages/list.vue
@@ -336,6 +336,7 @@ export default {
:images="images"
:metadata-loading="$apollo.queries.additionalDetails.loading"
:page-info="pageInfo"
+ :expiration-policy="config.expirationPolicy"
@delete="deleteImage"
@prev-page="fetchPreviousPage"
@next-page="fetchNextPage"
diff --git a/app/assets/javascripts/packages_and_registries/container_registry/explorer/utils.js b/app/assets/javascripts/packages_and_registries/container_registry/explorer/utils.js
new file mode 100644
index 00000000000..ffdaf9f2f17
--- /dev/null
+++ b/app/assets/javascripts/packages_and_registries/container_registry/explorer/utils.js
@@ -0,0 +1,8 @@
+import { approximateDuration, calculateRemainingMilliseconds } from '~/lib/utils/datetime_utility';
+
+export const timeTilRun = (time) => {
+ if (!time) return '';
+
+ const difference = calculateRemainingMilliseconds(time);
+ return approximateDuration(difference / 1000);
+};
diff --git a/app/assets/javascripts/packages_and_registries/package_registry/components/list/package_list_row.vue b/app/assets/javascripts/packages_and_registries/package_registry/components/list/package_list_row.vue
index 09988f4e1d9..04faff1a75b 100644
--- a/app/assets/javascripts/packages_and_registries/package_registry/components/list/package_list_row.vue
+++ b/app/assets/javascripts/packages_and_registries/package_registry/components/list/package_list_row.vue
@@ -159,7 +159,7 @@ export default {
-
+
This document attempts to specify Markdown syntax unambiguously. It contains many
-> examples with side-by-side Markdown and HTML. These are intended to double as conformance tests.
+> examples with side-by-side Markdown and HTML. These examples are intended to double as conformance tests.
The HTML-rendered versions of the specifications:
@@ -508,21 +508,76 @@ They are either downloaded, as in the case of the
GFM `spec.txt` file, or manually
updated, as in the case of all GFM files.
-- `glfm_specification/input/github_flavored_markdown/gfm_spec_v_0.29.txt` -
- official latest [GFM spec.txt](https://github.com/github/cmark-gfm/blob/master/test/spec.txt),
- automatically downloaded and updated by `update-specification.rb` script.
-- `glfm_specification/input/gitlab_flavored_markdown/glfm_intro.txt` -
- Manually updated text of intro section for generated GLFM `spec.txt`.
- - Replaces GFM version of introductory
- section in `spec.txt`.
-- `glfm_specification/input/gitlab_flavored_markdown/glfm_canonical_examples.txt` -
- Manually updated canonical Markdown+HTML examples for GLFM extensions.
- - Standard backtick-delimited `spec.txt` examples format with Markdown + canonical HTML.
- - Inserted as a new section before the appendix of generated `spec.txt`.
-- `glfm_specification/input/gitlab_flavored_markdown/glfm_example_status.yml` -
- Manually updated status of automatic generation of files based on Markdown
- examples.
- - Allows example snapshot generation, Markdown conformance tests, or
+##### GitHub Flavored Markdown specification
+
+[`glfm_specification/input/github_flavored_markdown/gfm_spec_v_0.29.txt`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/glfm_specification/input/github_flavored_markdown/gfm_spec_v_0.29.txt)
+is the official latest [GFM `spec.txt`](https://github.com/github/cmark-gfm/blob/master/test/spec.txt).
+
+- It is automatically downloaded and updated by `update-specification.rb` script.
+- When it is downloaded, the version number is added to the filename.
+
+##### `glfm_intro.txt`
+
+[`glfm_specification/input/gitlab_flavored_markdown/glfm_intro.txt`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/glfm_specification/input/gitlab_flavored_markdown/glfm_intro.txt)
+is the GitLab-specific version of the prose in the introduction section of the GLFM specification.
+
+- It is manually updated.
+- The `update-specification.rb` script inserts it into the generated GLFM `spec.txt` to replace
+ the GitHub-specific GFM version of the introductory section.
+
+##### `glfm_canonical_examples.txt`
+
+[`glfm_specification/input/gitlab_flavored_markdown/glfm_canonical_examples.txt`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/glfm_specification/input/gitlab_flavored_markdown/glfm_canonical_examples.txt)
+is the manually updated canonical Markdown+HTML examples for GLFM extensions.
+
+- It contains examples in the [standard backtick-delimited `spec.txt` format](#various-markdown-specifications),
+ each of which contain a Markdown example and the corresponding canonical HTML.
+- The `update-specification.rb` script inserts it as new sections before the appendix
+ of generated `spec.txt`.
+- It should consist of `H1` header sections, with a examples nested exactly 2 levels deep within `H2`
+ header sections.
+
+`glfm_specification/input/gitlab_flavored_markdown/glfm_canonical_examples.txt` sample entries:
+
+NOTE:
+All lines in this example are prefixed with a `|` character. This prefix helps avoid false
+errors when this file is checked by `markdownlint`, and possible errors in other Markdown editors.
+The actual file should not have these prefixed `|` characters.
+
+```plaintext
+|# First GitLab-Specific Section with Examples
+|
+|## Strong but with two asterisks
+|
+|```````````````````````````````` example
+|**bold**
+|.
+|
+```````````````````````````````` + + +## Insecure characters + +For security reasons, the Unicode character `U+0000` must be replaced +with the REPLACEMENT CHARACTER (`U+FFFD`). + +# Blocks and inlines + +We can think of a document as a sequence of +[blocks](@)---structural elements like paragraphs, block +quotations, lists, headings, rules, and code blocks. Some blocks (like +block quotes and list items) contain other blocks; others (like +headings and paragraphs) contain [inline](@) content---text, +links, emphasized text, images, code spans, and so on. + +## Precedence + +Indicators of block structure always take precedence over indicators +of inline structure. So, for example, the following is a list with +two items, not a list with one item containing a code span: + +```````````````````````````````` example +- `one +- two` +. +
+
+
+```````````````````````````````` + + +Wrong characters: + +```````````````````````````````` example ++++ +. +
+
+
+```````````````````````````````` + + +Four spaces is too many: + +```````````````````````````````` example + *** +. +
+```````````````````````````````` + + +Spaces are allowed between the characters: + +```````````````````````````````` example + - - - +. +
+```````````````````````````````` + + +```````````````````````````````` example + ** * ** * ** * ** +. +
+```````````````````````````````` + + +```````````````````````````````` example +- - - - +. +
+```````````````````````````````` + + +Spaces are allowed at the end: + +```````````````````````````````` example +- - - - +. +
+```````````````````````````````` + + +However, no other characters may occur in the line: + +```````````````````````````````` example +_ _ _ _ a + +a------ + +---a--- +. +
+
+
+
+
+```````````````````````````````` + + +```````````````````````````````` example +Foo bar +# baz +Bar foo +. +
+```````````````````````````````` + + +The setext heading underline can be indented up to three spaces, and +may have trailing spaces: + +```````````````````````````````` example +Foo + ---- +. +
+```````````````````````````````` + + +Trailing spaces in the content line do not cause a line break: + +```````````````````````````````` example +Foo +----- +. +
+```````````````````````````````` + + +```````````````````````````````` example +> foo +bar +=== +. +
+```````````````````````````````` + + +A blank line is needed between a paragraph and a following +setext heading, since otherwise the paragraph becomes part +of the heading's content: + +```````````````````````````````` example +Foo +Bar +--- +. +
+
+
+```````````````````````````````` + + +```````````````````````````````` example +- foo +----- +. +
+```````````````````````````````` + + +```````````````````````````````` example + foo +--- +. +
+```````````````````````````````` + + +```````````````````````````````` example +> foo +----- +. +
+```````````````````````````````` + + +If you want a heading with `> foo` as its literal text, you can +use backslash escapes: + +```````````````````````````````` example +\> foo +------ +. +
+
+
+```````````````````````````````` + + +The first line can be indented more than four spaces: + +```````````````````````````````` example + foo + bar +. +`, or the end of the line.\
+**End condition:** line contains an end tag
+``, ``, or `` (case-insensitive; it
+need not match the start tag).
+
+2. **Start condition:** line begins with the string ``.
+
+3. **Start condition:** line begins with the string ``.
+
+4. **Start condition:** line begins with the string ``.
+
+5. **Start condition:** line begins with the string
+``.
+
+6. **Start condition:** line begins the string `<` or ``, or
+the string `/>`.\
+**End condition:** line is followed by a [blank line].
+
+7. **Start condition:** line begins with a complete [open tag]
+(with any [tag name] other than `script`,
+`style`, or `pre`) or a complete [closing tag],
+followed only by [whitespace] or the end of the line.\
+**End condition:** line is followed by a [blank line].
+
+HTML blocks continue until they are closed by their appropriate
+[end condition], or the last line of the document or other [container
+block](#container-blocks). This means any HTML **within an HTML
+block** that might otherwise be recognised as a start condition will
+be ignored by the parser and passed through as-is, without changing
+the parser's state.
+
+For instance, `
bold
+|```````````````````````````````` +| +|# Second GitLab-Specific Section with Examples +| +|## Strong but with HTML +| +|```````````````````````````````` example +| +|bold +| +|. +|+|bold +|
+|```````````````````````````````` +``` + +##### `glfm_example_status.yml` + +[`glfm_specification/input/gitlab_flavored_markdown/glfm_example_status.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/glfm_specification/input/gitlab_flavored_markdown/glfm_example_status.yml) +controls the behavior of the [scripts](#scripts) and [tests](#types-of-markdown-tests-driven-by-the-glfm-specification). + +- It is manually updated. +- It controls the status of automatic generation of files based on Markdown examples. +- It allows example snapshot generation, Markdown conformance tests, or Markdown snapshot tests to be skipped for individual examples. For example, if they are unimplemented, broken, or cannot be tested for some reason. @@ -545,28 +600,39 @@ updated, as in the case of all GFM files. The `glfm_specification/output` directory contains the CommonMark standard format `spec.txt` file which represents the canonical GLFM specification which is generated by the `update-specification.rb` script. It also contains the rendered `spec.html` -and `spec.pdf` which are generated from with the `spec.txt` as input. +which is generated based on the `spec.txt` as input. -- `glfm_specification/output/spec.txt` - A Markdown file, in the standard format - with prose and Markdown + canonical HTML examples, generated (or updated) by the - `update-specification.rb` script. -- `glfm_specification/output/spec.html` - An HTML file, rendered based on `spec.txt`, - also generated (or updated) by the `update-specification.rb` script at the same time as - `spec.txt`. It corresponds to the HTML-rendered versions of the - "GitHub Flavored Markdown" (GFM) - [specification](https://github.github.com/gfm/) - and the [CommonMark specification](https://spec.commonmark.org/0.30/). - -These output `spec.**` files, which represent the official, canonical GLFM specification +These output `spec.*` files, which represent the official, canonical GLFM specification, are colocated under the same parent folder `glfm_specification` with the other `input` specification files. They're located here both for convenience, and because they are all -a mix of manually edited and generated files. In GFM, -`spec.txt` is [located in the test dir](https://github.com/github/cmark-gfm/blob/master/test/spec.txt), -and in CommonMark it's located -[in the project root](https://github.com/github/cmark-gfm/blob/master/test/spec.txt). -No precedent exists for a standard location. In the future, we may decide to +a mix of manually edited and generated files. + +In GFM, `spec.txt` is [located in the test dir](https://github.com/github/cmark-gfm/blob/master/test/spec.txt), +and in CommonMark it's located [in the project root](https://github.com/github/cmark-gfm/blob/master/test/spec.txt). No precedent exists for a standard location. In the future, we may decide to move or copy a hosted version of the rendered HTML `spec.html` version to another location or site. +##### spec.txt + +[`glfm_specification/output/spec.txt`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/glfm_specification/output/spec.txt) +is a Markdown specification file, in the standard format +with prose and Markdown + canonical HTML examples. It is generated or updated by the +`update-specification.rb` script. + +It also serves as input for other scripts such as `update-example-snapshots.rb` +and `run-spec-tests.sh`. + +##### spec.html + +[`glfm_specification/output/spec.html`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/glfm_specification/output/spec.html) +is an HTML file, rendered based on `spec.txt`. It is +also generated (or updated) by the `update-specification.rb` script at the same time as +`spec.txt`. + +It corresponds to the HTML-rendered versions of the +"GitHub Flavored Markdown" (GFM) +[specification](https://github.github.com/gfm/) +and the [CommonMark specification](https://spec.commonmark.org/0.30/). + ### Example snapshot files The `example_snapshots` directory contains files which are generated by the @@ -578,12 +644,13 @@ After the entire GLFM implementation is complete for both backend (Ruby) and frontend (JavaScript), all of these YAML files can be automatically generated. However, while the implementations are still in progress, the `skip_update_example_snapshots` key in `glfm_specification/input/gitlab_flavored_markdown/glfm_example_status.yml` -can be used to disable automatic generation of some examples, and they can instead +can be used to disable automatic generation of some examples. They can instead be manually edited as necessary to help drive the implementations. #### `spec/fixtures/glfm/example_snapshots/examples_index.yml` -`spec/fixtures/glfm/example_snapshots/examples_index.yml` is the main list of all +[`spec/fixtures/glfm/example_snapshots/examples_index.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/spec/fixtures/glfm/example_snapshots/examples_index.yml) +is the main list of all CommonMark, GFM, and GLFM example names, each with a unique canonical name. - It is generated from the hierarchical sections and examples in the @@ -594,10 +661,15 @@ CommonMark, GFM, and GLFM example names, each with a unique canonical name. the additional Section 7 in the GLFM `spec.txt`. - It also contains extra metadata about each example, such as: 1. `spec_txt_example_position` - The position of the example in the generated GLFM `spec.txt` file. + - This value is the index order of each individual Markdown + HTML5 example in the file. It is _not_ + the line number in the file. + - This value can be used to locate the example in the rendered `spec.html` file, because the standard + CommonMark tooling includes the index number for each example in the rendered HTML file. + For example: [https://spec.commonmark.org/0.30/#example-42](https://spec.commonmark.org/0.30/#example-42) 1. `source_specification` - Which specification the example originally came from: `commonmark`, `github`, or `gitlab`. - The naming convention for example entry names is based on nested header section - names and example index within the header. + names and example index in the header. - This naming convention should result in fairly stable names and example positions. The CommonMark / GLFM specification rarely changes, and most GLFM examples where multiple examples exist for the same Section 7 subsection are @@ -625,7 +697,7 @@ CommonMark, GFM, and GLFM example names, each with a unique canonical name. #### `spec/fixtures/glfm/example_snapshots/markdown.yml` -`spec/fixtures/glfm/example_snapshots/markdown.yml` contains the original Markdown +[`spec/fixtures/glfm/example_snapshots/markdown.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/spec/fixtures/glfm/example_snapshots/markdown.yml) contains the original Markdown for each entry in `spec/fixtures/glfm/example_snapshots/examples_index.yml` - For CommonMark and GFM Markdown, @@ -644,8 +716,8 @@ for each entry in `spec/fixtures/glfm/example_snapshots/examples_index.yml` #### `spec/fixtures/glfm/example_snapshots/html.yml` -`spec/fixtures/glfm/example_snapshots/html.yml` contains the HTML for each entry in -`spec/fixtures/glfm/example_snapshots/examples_index.yml` +[`spec/fixtures/glfm/example_snapshots/html.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/spec/fixtures/glfm/example_snapshots/html.yml) +contains the HTML for each entry in `spec/fixtures/glfm/example_snapshots/examples_index.yml` Three types of entries exist, with different HTML for each: @@ -688,8 +760,8 @@ depending on how the implementations evolve. #### `spec/fixtures/glfm/example_snapshots/prosemirror_json.yml` -`spec/fixtures/glfm/example_snapshots/prosemirror_json.yml` contains the ProseMirror -JSON for each entry in `spec/fixtures/glfm/example_snapshots/examples_index.yml` +[`spec/fixtures/glfm/example_snapshots/prosemirror_json.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/spec/fixtures/glfm/example_snapshots/prosemirror_json.yml) +contains the ProseMirror JSON for each entry in `spec/fixtures/glfm/example_snapshots/examples_index.yml` - It is generated (or updated) from the frontend code via the `update-example-snapshots.rb` script, but can be manually updated for examples with incomplete implementations. diff --git a/doc/update/upgrading_from_source.md b/doc/update/upgrading_from_source.md index 1c9f35e0601..e239ce6ae63 100644 --- a/doc/update/upgrading_from_source.md +++ b/doc/update/upgrading_from_source.md @@ -7,10 +7,6 @@ comments: false # Upgrading Community Edition and Enterprise Edition from source **(FREE SELF)** -NOTE: -Users wishing to upgrade to 12.0.0 must take some extra steps. See the -version specific upgrade instructions for 12.0.0 for more details. - Make sure you view this update guide from the branch (version) of GitLab you would like to install (for example, `11.8`). You can select the required version of documentation in the dropdown at the top right corner of GitLab documentation page. @@ -421,6 +417,39 @@ Example: Additional instructions here. --> +### 15.0.0 + +Support for more than one database has been added to GitLab. [As part of this](https://gitlab.com/gitlab-org/gitlab/-/issues/338182), +`config/database.yml` needs to include a database name in the database configuration. +The `main: database` must be first. If an invalid or deprecated syntax is used, an error is generated +during application start: + +```plaintext +ERROR: This installation of GitLab uses unsupported 'config/database.yml'. +The main: database needs to be defined as a first configuration item instead of primary. (RuntimeError) +``` + +Previously, the `config/database.yml` file looked like the following: + +```yaml +production: + adapter: postgresql + encoding: unicode + database: gitlabhq_production + ... +``` + +Starting with GitLab 15.0, it needs to define a `main` database first: + +```yaml +production: + main: + adapter: postgresql + encoding: unicode + database: gitlabhq_production + ... +``` + ### 14.5.0 As part of [enabling real-time issue assignees](https://gitlab.com/gitlab-org/gitlab/-/issues/330117), Action Cable is now enabled by default, and requires `config/cable.yml` to be present. diff --git a/doc/user/application_security/vulnerability_report/index.md b/doc/user/application_security/vulnerability_report/index.md index 7cadc73e8c3..cda9c4eccf0 100644 --- a/doc/user/application_security/vulnerability_report/index.md +++ b/doc/user/application_security/vulnerability_report/index.md @@ -230,6 +230,7 @@ To undo this action, select a different status from the same menu. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/301003) in GitLab 14.9. Disabled by default. > - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/353796) in GitLab 14.10. +> - [Feature flag `new_vulnerability_form`](https://gitlab.com/gitlab-org/gitlab/-/issues/359049) removed in GitLab 15.0. To add a new vulnerability finding from your project level Vulnerability Report page: diff --git a/doc/user/infrastructure/clusters/migrate_to_gitlab_agent.md b/doc/user/infrastructure/clusters/migrate_to_gitlab_agent.md index b9f13e0239a..7b2b5b4afd4 100644 --- a/doc/user/infrastructure/clusters/migrate_to_gitlab_agent.md +++ b/doc/user/infrastructure/clusters/migrate_to_gitlab_agent.md @@ -14,11 +14,10 @@ To connect your Kubernetes cluster with GitLab, you can use: The certificate-based integration is [**deprecated**](https://about.gitlab.com/blog/2021/11/15/deprecating-the-cert-based-kubernetes-integration/) -in GitLab 14.5. The removal dates are: +in GitLab 14.5. The sunsetting plans are described: -- [GitLab.com customers](../../../update/deprecations.md#saas-certificate-based-integration-with-kubernetes): GitLab 15.0. -- [Self-managed customers](../../../update/deprecations.md#self-managed-certificate-based-integration-with-kubernetes): - Placed behind a disabled feature flag in GitLab 15.0, and removed entirely in GitLab 15.6. +- for [GitLab.com customers](../../../update/deprecations.md#saas-certificate-based-integration-with-kubernetes). +- for [Self-managed customers](../../../update/deprecations.md#self-managed-certificate-based-integration-with-kubernetes). If you are using the certificate-based integration, you should move to another workflow as soon as possible. diff --git a/doc/user/project/merge_requests/test_coverage_visualization.md b/doc/user/project/merge_requests/test_coverage_visualization.md index c237452c01d..42324205033 100644 --- a/doc/user/project/merge_requests/test_coverage_visualization.md +++ b/doc/user/project/merge_requests/test_coverage_visualization.md @@ -196,7 +196,9 @@ coverage-jdk11: needs: ["test-jdk11"] artifacts: reports: - cobertura: target/site/cobertura.xml + coverage_report: + coverage_format: cobertura + path: target/site/cobertura.xml ``` #### Gradle example @@ -232,7 +234,9 @@ coverage-jdk11: needs: ["test-jdk11"] artifacts: reports: - cobertura: build/cobertura.xml + coverage_report: + coverage_format: cobertura + path: build/cobertura.xml ``` ### Python example @@ -254,7 +258,9 @@ run tests: coverage: '/TOTAL.*\s([.\d]+)%/' artifacts: reports: - cobertura: coverage.xml + coverage_report: + coverage_format: cobertura + path: coverage.xml ``` ### PHP example @@ -284,7 +290,9 @@ run tests: - php ./vendor/bin/phpunit --coverage-text --coverage-cobertura=coverage.cobertura.xml artifacts: reports: - cobertura: coverage.cobertura.xml + coverage_report: + coverage_format: cobertura + path: coverage.cobertura.xml ``` [Codeception](https://codeception.com/), through PHPUnit, also supports generating Cobertura report with @@ -319,7 +327,9 @@ run tests: name: ${CI_JOB_NAME}-${CI_COMMIT_REF_NAME}-${CI_COMMIT_SHA} expire_in: 2 days reports: - cobertura: build/coverage.xml + coverage_report: + coverage_format: cobertura + path: build/coverage.xml ``` ### Go example @@ -346,7 +356,9 @@ run tests: - go run github.com/boumenot/gocover-cobertura < coverage.txt > coverage.xml artifacts: reports: - cobertura: coverage.xml + coverage_report: + coverage_format: cobertura + path: coverage.xml ``` ### Ruby example @@ -373,5 +385,7 @@ run tests: - bundle exec rspec artifacts: reports: - cobertura: coverage/coverage.xml + coverage_report: + coverage_format: cobertura + path: coverage/coverage.xml ``` diff --git a/glfm_specification/input/github_flavored_markdown/ghfm_spec_v_0.29.txt b/glfm_specification/input/github_flavored_markdown/ghfm_spec_v_0.29.txt new file mode 100644 index 00000000000..582131d700a --- /dev/null +++ b/glfm_specification/input/github_flavored_markdown/ghfm_spec_v_0.29.txt @@ -0,0 +1,10227 @@ +--- +title: GitHub Flavored Markdown Spec +version: 0.29 +date: '2019-04-06' +license: '[CC-BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/)' +... + +# Introduction + +## What is GitHub Flavored Markdown? + +GitHub Flavored Markdown, often shortened as GFM, is the dialect of Markdown +that is currently supported for user content on GitHub.com and GitHub +Enterprise. + +This formal specification, based on the CommonMark Spec, defines the syntax and +semantics of this dialect. + +GFM is a strict superset of CommonMark. All the features which are supported in +GitHub user content and that are not specified on the original CommonMark Spec +are hence known as **extensions**, and highlighted as such. + +While GFM supports a wide range of inputs, it's worth noting that GitHub.com +and GitHub Enterprise perform additional post-processing and sanitization after +GFM is converted to HTML to ensure security and consistency of the website. + +## What is Markdown? + +Markdown is a plain text format for writing structured documents, +based on conventions for indicating formatting in email +and usenet posts. It was developed by John Gruber (with +help from Aaron Swartz) and released in 2004 in the form of a +[syntax description](http://daringfireball.net/projects/markdown/syntax) +and a Perl script (`Markdown.pl`) for converting Markdown to +HTML. In the next decade, dozens of implementations were +developed in many languages. Some extended the original +Markdown syntax with conventions for footnotes, tables, and +other document elements. Some allowed Markdown documents to be +rendered in formats other than HTML. Websites like Reddit, +StackOverflow, and GitHub had millions of people using Markdown. +And Markdown started to be used beyond the web, to author books, +articles, slide shows, letters, and lecture notes. + +What distinguishes Markdown from many other lightweight markup +syntaxes, which are often easier to write, is its readability. +As Gruber writes: + +> The overriding design goal for Markdown's formatting syntax is +> to make it as readable as possible. The idea is that a +> Markdown-formatted document should be publishable as-is, as +> plain text, without looking like it's been marked up with tags +> or formatting instructions. +> (` tags? Can a list be partially "loose" and partially + "tight"? What should we do with a list like this? + + ``` markdown + 1. one + + 2. two + 3. three + ``` + + Or this? + + ``` markdown + 1. one + - a + + - b + 2. two + ``` + + (There are some relevant comments by John Gruber + [here](http://article.gmane.org/gmane.text.markdown.general/2554).) + +5. Can list markers be indented? Can ordered list markers be right-aligned? + + ``` markdown + 8. item 1 + 9. item 2 + 10. item 2a + ``` + +6. Is this one list with a thematic break in its second item, + or two lists separated by a thematic break? + + ``` markdown + * a + * * * * * + * b + ``` + +7. When list markers change from numbers to bullets, do we have + two lists or one? (The Markdown syntax description suggests two, + but the perl scripts and many other implementations produce one.) + + ``` markdown + 1. fee + 2. fie + - foe + - fum + ``` + +8. What are the precedence rules for the markers of inline structure? + For example, is the following a valid link, or does the code span + take precedence ? + + ``` markdown + [a backtick (`)](/url) and [another backtick (`)](/url). + ``` + +9. What are the precedence rules for markers of emphasis and strong + emphasis? For example, how should the following be parsed? + + ``` markdown + *foo *bar* baz* + ``` + +10. What are the precedence rules between block-level and inline-level + structure? For example, how should the following be parsed? + + ``` markdown + - `a long code span can contain a hyphen like this + - and it can screw things up` + ``` + +11. Can list items include section headings? (`Markdown.pl` does not + allow this, but does allow blockquotes to include headings.) + + ``` markdown + - # Heading + ``` + +12. Can list items be empty? + + ``` markdown + * a + * + * b + ``` + +13. Can link references be defined inside block quotes or list items? + + ``` markdown + > Blockquote [foo]. + > + > [foo]: /url + ``` + +14. If there are multiple definitions for the same reference, which takes + precedence? + + ``` markdown + [foo]: /url1 + [foo]: /url2 + + [foo][] + ``` + +In the absence of a spec, early implementers consulted `Markdown.pl` +to resolve these ambiguities. But `Markdown.pl` was quite buggy, and +gave manifestly bad results in many cases, so it was not a +satisfactory replacement for a spec. + +Because there is no unambiguous spec, implementations have diverged +considerably. As a result, users are often surprised to find that +a document that renders one way on one system (say, a GitHub wiki) +renders differently on another (say, converting to docbook using +pandoc). To make matters worse, because nothing in Markdown counts +as a "syntax error," the divergence often isn't discovered right away. + +## About this document + +This document attempts to specify Markdown syntax unambiguously. +It contains many examples with side-by-side Markdown and +HTML. These are intended to double as conformance tests. An +accompanying script `spec_tests.py` can be used to run the tests +against any Markdown program: + + python test/spec_tests.py --spec spec.txt --program PROGRAM + +Since this document describes how Markdown is to be parsed into +an abstract syntax tree, it would have made sense to use an abstract +representation of the syntax tree instead of HTML. But HTML is capable +of representing the structural distinctions we need to make, and the +choice of HTML for the tests makes it possible to run the tests against +an implementation without writing an abstract syntax tree renderer. + +This document is generated from a text file, `spec.txt`, written +in Markdown with a small extension for the side-by-side tests. +The script `tools/makespec.py` can be used to convert `spec.txt` into +HTML or CommonMark (which can then be converted into other formats). + +In the examples, the `→` character is used to represent tabs. + +# Preliminaries + +## Characters and lines + +Any sequence of [characters] is a valid CommonMark +document. + +A [character](@) is a Unicode code point. Although some +code points (for example, combining accents) do not correspond to +characters in an intuitive sense, all code points count as characters +for purposes of this spec. + +This spec does not specify an encoding; it thinks of lines as composed +of [characters] rather than bytes. A conforming parser may be limited +to a certain encoding. + +A [line](@) is a sequence of zero or more [characters] +other than newline (`U+000A`) or carriage return (`U+000D`), +followed by a [line ending] or by the end of file. + +A [line ending](@) is a newline (`U+000A`), a carriage return +(`U+000D`) not followed by a newline, or a carriage return and a +following newline. + +A line containing no characters, or a line containing only spaces +(`U+0020`) or tabs (`U+0009`), is called a [blank line](@). + +The following definitions of character classes will be used in this spec: + +A [whitespace character](@) is a space +(`U+0020`), tab (`U+0009`), newline (`U+000A`), line tabulation (`U+000B`), +form feed (`U+000C`), or carriage return (`U+000D`). + +[Whitespace](@) is a sequence of one or more [whitespace +characters]. + +A [Unicode whitespace character](@) is +any code point in the Unicode `Zs` general category, or a tab (`U+0009`), +carriage return (`U+000D`), newline (`U+000A`), or form feed +(`U+000C`). + +[Unicode whitespace](@) is a sequence of one +or more [Unicode whitespace characters]. + +A [space](@) is `U+0020`. + +A [non-whitespace character](@) is any character +that is not a [whitespace character]. + +An [ASCII punctuation character](@) +is `!`, `"`, `#`, `$`, `%`, `&`, `'`, `(`, `)`, +`*`, `+`, `,`, `-`, `.`, `/` (U+0021–2F), +`:`, `;`, `<`, `=`, `>`, `?`, `@` (U+003A–0040), +`[`, `\`, `]`, `^`, `_`, `` ` `` (U+005B–0060), +`{`, `|`, `}`, or `~` (U+007B–007E). + +A [punctuation character](@) is an [ASCII +punctuation character] or anything in +the general Unicode categories `Pc`, `Pd`, `Pe`, `Pf`, `Pi`, `Po`, or `Ps`. + +## Tabs + +Tabs in lines are not expanded to [spaces]. However, +in contexts where whitespace helps to define block structure, +tabs behave as if they were replaced by spaces with a tab stop +of 4 characters. + +Thus, for example, a tab can be used instead of four spaces +in an indented code block. (Note, however, that internal +tabs are passed through as literal tabs, not expanded to +spaces.) + +```````````````````````````````` example +→foo→baz→→bim +. +
foo→baz→→bim
+foo→baz→→bim
+a→a
+ὐ→a
+-
+
-
+
foo
+bar
+
+
-
+
-
+
foo
+
+bar +
+
++```````````````````````````````` + +```````````````````````````````` example +-→→foo +. ++foo +
-
+
-
+
+foo +
+
foo
+bar
+-
+
- foo
+
-
+
- bar
+
-
+
- baz +
+
+ - bar
+
Foo
+```````````````````````````````` + +```````````````````````````````` example +*→*→*→ +. ++```````````````````````````````` + + +## Insecure characters + +For security reasons, the Unicode character `U+0000` must be replaced +with the REPLACEMENT CHARACTER (`U+FFFD`). + +# Blocks and inlines + +We can think of a document as a sequence of +[blocks](@)---structural elements like paragraphs, block +quotations, lists, headings, rules, and code blocks. Some blocks (like +block quotes and list items) contain other blocks; others (like +headings and paragraphs) contain [inline](@) content---text, +links, emphasized text, images, code spans, and so on. + +## Precedence + +Indicators of block structure always take precedence over indicators +of inline structure. So, for example, the following is a list with +two items, not a list with one item containing a code span: + +```````````````````````````````` example +- `one +- two` +. +
-
+
- `one +
- two` +
+
+
+```````````````````````````````` + + +Wrong characters: + +```````````````````````````````` example ++++ +. +
+++
+```````````````````````````````` + + +```````````````````````````````` example +=== +. +===
+```````````````````````````````` + + +Not enough characters: + +```````````````````````````````` example +-- +** +__ +. +-- +** +__
+```````````````````````````````` + + +One to three spaces indent are allowed: + +```````````````````````````````` example + *** + *** + *** +. ++
+
+```````````````````````````````` + + +Four spaces is too many: + +```````````````````````````````` example + *** +. +
***
+Foo +***
+```````````````````````````````` + + +More than three characters may be used: + +```````````````````````````````` example +_____________________________________ +. ++```````````````````````````````` + + +Spaces are allowed between the characters: + +```````````````````````````````` example + - - - +. +
+```````````````````````````````` + + +```````````````````````````````` example + ** * ** * ** * ** +. +
+```````````````````````````````` + + +```````````````````````````````` example +- - - - +. +
+```````````````````````````````` + + +Spaces are allowed at the end: + +```````````````````````````````` example +- - - - +. +
+```````````````````````````````` + + +However, no other characters may occur in the line: + +```````````````````````````````` example +_ _ _ _ a + +a------ + +---a--- +. +
_ _ _ _ a
+a------
+---a---
+```````````````````````````````` + + +It is required that all of the [non-whitespace characters] be the same. +So, this is not a thematic break: + +```````````````````````````````` example + *-* +. +-
+```````````````````````````````` + + +Thematic breaks do not need blank lines before or after: + +```````````````````````````````` example +- foo +*** +- bar +. +-
+
- foo +
+
-
+
- bar +
Foo
++
bar
+```````````````````````````````` + + +If a line of dashes that meets the above conditions for being a +thematic break could also be interpreted as the underline of a [setext +heading], the interpretation as a +[setext heading] takes precedence. Thus, for example, +this is a setext heading, not a paragraph followed by a thematic break: + +```````````````````````````````` example +Foo +--- +bar +. +Foo
+bar
+```````````````````````````````` + + +When both a thematic break and a list item are possible +interpretations of a line, the thematic break takes precedence: + +```````````````````````````````` example +* Foo +* * * +* Bar +. +-
+
- Foo +
+
-
+
- Bar +
-
+
- Foo +
-
+
+
+
foo
+foo
+foo
+foo
+foo
+foo
+```````````````````````````````` + + +More than six `#` characters is not a heading: + +```````````````````````````````` example +####### foo +. +####### foo
+```````````````````````````````` + + +At least one space is required between the `#` characters and the +heading's contents, unless the heading is empty. Note that many +implementations currently do not require the space. However, the +space was required by the +[original ATX implementation](http://www.aaronsw.com/2002/atx/atx.py), +and it helps prevent things like the following from being parsed as +headings: + +```````````````````````````````` example +#5 bolt + +#hashtag +. +#5 bolt
+#hashtag
+```````````````````````````````` + + +This is not a heading, because the first `#` is escaped: + +```````````````````````````````` example +\## foo +. +## foo
+```````````````````````````````` + + +Contents are parsed as inlines: + +```````````````````````````````` example +# foo *bar* \*baz\* +. +foo bar *baz*
+```````````````````````````````` + + +Leading and trailing [whitespace] is ignored in parsing inline content: + +```````````````````````````````` example +# foo +. +foo
+```````````````````````````````` + + +One to three spaces indentation are allowed: + +```````````````````````````````` example + ### foo + ## foo + # foo +. +foo
+foo
+foo
+```````````````````````````````` + + +Four spaces are too much: + +```````````````````````````````` example + # foo +. +# foo
+foo +# bar
+```````````````````````````````` + + +A closing sequence of `#` characters is optional: + +```````````````````````````````` example +## foo ## + ### bar ### +. +foo
+bar
+```````````````````````````````` + + +It need not be the same length as the opening sequence: + +```````````````````````````````` example +# foo ################################## +##### foo ## +. +foo
+foo
+```````````````````````````````` + + +Spaces are allowed after the closing sequence: + +```````````````````````````````` example +### foo ### +. +foo
+```````````````````````````````` + + +A sequence of `#` characters with anything but [spaces] following it +is not a closing sequence, but counts as part of the contents of the +heading: + +```````````````````````````````` example +### foo ### b +. +foo ### b
+```````````````````````````````` + + +The closing sequence must be preceded by a space: + +```````````````````````````````` example +# foo# +. +foo#
+```````````````````````````````` + + +Backslash-escaped `#` characters do not count as part +of the closing sequence: + +```````````````````````````````` example +### foo \### +## foo #\## +# foo \# +. +foo ###
+foo ###
+foo #
+```````````````````````````````` + + +ATX headings need not be separated from surrounding content by blank +lines, and they can interrupt paragraphs: + +```````````````````````````````` example +**** +## foo +**** +. ++
foo
++```````````````````````````````` + + +```````````````````````````````` example +Foo bar +# baz +Bar foo +. +
Foo bar
+baz
+Bar foo
+```````````````````````````````` + + +ATX headings can be empty: + +```````````````````````````````` example +## +# +### ### +. + + + +```````````````````````````````` + + +## Setext headings + +A [setext heading](@) consists of one or more +lines of text, each containing at least one [non-whitespace +character], with no more than 3 spaces indentation, followed by +a [setext heading underline]. The lines of text must be such +that, were they not followed by the setext heading underline, +they would be interpreted as a paragraph: they cannot be +interpretable as a [code fence], [ATX heading][ATX headings], +[block quote][block quotes], [thematic break][thematic breaks], +[list item][list items], or [HTML block][HTML blocks]. + +A [setext heading underline](@) is a sequence of +`=` characters or a sequence of `-` characters, with no more than 3 +spaces indentation and any number of trailing spaces. If a line +containing a single `-` can be interpreted as an +empty [list items], it should be interpreted this way +and not as a [setext heading underline]. + +The heading is a level 1 heading if `=` characters are used in +the [setext heading underline], and a level 2 heading if `-` +characters are used. The contents of the heading are the result +of parsing the preceding lines of text as CommonMark inline +content. + +In general, a setext heading need not be preceded or followed by a +blank line. However, it cannot interrupt a paragraph, so when a +setext heading comes after a paragraph, a blank line is needed between +them. + +Simple examples: + +```````````````````````````````` example +Foo *bar* +========= + +Foo *bar* +--------- +. +Foo bar
+Foo bar
+```````````````````````````````` + + +The content of the header may span more than one line: + +```````````````````````````````` example +Foo *bar +baz* +==== +. +Foo bar +baz
+```````````````````````````````` + +The contents are the result of parsing the headings's raw +content as inlines. The heading's raw content is formed by +concatenating the lines and removing initial and final +[whitespace]. + +```````````````````````````````` example + Foo *bar +baz*→ +==== +. +Foo bar +baz
+```````````````````````````````` + + +The underlining can be any length: + +```````````````````````````````` example +Foo +------------------------- + +Foo += +. +Foo
+Foo
+```````````````````````````````` + + +The heading content can be indented up to three spaces, and need +not line up with the underlining: + +```````````````````````````````` example + Foo +--- + + Foo +----- + + Foo + === +. +Foo
+Foo
+Foo
+```````````````````````````````` + + +Four spaces indent is too much: + +```````````````````````````````` example + Foo + --- + + Foo +--- +. +Foo
+---
+
+Foo
++```````````````````````````````` + + +The setext heading underline can be indented up to three spaces, and +may have trailing spaces: + +```````````````````````````````` example +Foo + ---- +. +
Foo
+```````````````````````````````` + + +Four spaces is too much: + +```````````````````````````````` example +Foo + --- +. +Foo +---
+```````````````````````````````` + + +The setext heading underline cannot contain internal spaces: + +```````````````````````````````` example +Foo += = + +Foo +--- - +. +Foo += =
+Foo
++```````````````````````````````` + + +Trailing spaces in the content line do not cause a line break: + +```````````````````````````````` example +Foo +----- +. +
Foo
+```````````````````````````````` + + +Nor does a backslash at the end: + +```````````````````````````````` example +Foo\ +---- +. +Foo\
+```````````````````````````````` + + +Since indicators of block structure take precedence over +indicators of inline structure, the following are setext headings: + +```````````````````````````````` example +`Foo +---- +` + + +. +`Foo
+`
+<a title="a lot
+of dashes"/>
+```````````````````````````````` + + +The setext heading underline cannot be a [lazy continuation +line] in a list item or block quote: + +```````````````````````````````` example +> Foo +--- +. +++Foo
+
+```````````````````````````````` + + +```````````````````````````````` example +> foo +bar +=== +. +
++```````````````````````````````` + + +```````````````````````````````` example +- Foo +--- +. +foo +bar +===
+
-
+
- Foo +
+```````````````````````````````` + + +A blank line is needed between a paragraph and a following +setext heading, since otherwise the paragraph becomes part +of the heading's content: + +```````````````````````````````` example +Foo +Bar +--- +. +
Foo +Bar
+```````````````````````````````` + + +But in general a blank line is not required before or after +setext headings: + +```````````````````````````````` example +--- +Foo +--- +Bar +--- +Baz +. ++
Foo
+Bar
+Baz
+```````````````````````````````` + + +Setext headings cannot be empty: + +```````````````````````````````` example + +==== +. +====
+```````````````````````````````` + + +Setext heading text lines must not be interpretable as block +constructs other than paragraphs. So, the line of dashes +in these examples gets interpreted as a thematic break: + +```````````````````````````````` example +--- +--- +. ++
+```````````````````````````````` + + +```````````````````````````````` example +- foo +----- +. +
-
+
- foo +
+```````````````````````````````` + + +```````````````````````````````` example + foo +--- +. +
foo
++```````````````````````````````` + + +```````````````````````````````` example +> foo +----- +. +
++foo
+
+```````````````````````````````` + + +If you want a heading with `> foo` as its literal text, you can +use backslash escapes: + +```````````````````````````````` example +\> foo +------ +. +
> foo
+```````````````````````````````` + + +**Compatibility note:** Most existing Markdown implementations +do not allow the text of setext headings to span multiple lines. +But there is no consensus about how to interpret + +``` markdown +Foo +bar +--- +baz +``` + +One can find four different interpretations: + +1. paragraph "Foo", heading "bar", paragraph "baz" +2. paragraph "Foo bar", thematic break, paragraph "baz" +3. paragraph "Foo bar --- baz" +4. heading "Foo bar", paragraph "baz" + +We find interpretation 4 most natural, and interpretation 4 +increases the expressive power of CommonMark, by allowing +multiline headings. Authors who want interpretation 1 can +put a blank line after the first paragraph: + +```````````````````````````````` example +Foo + +bar +--- +baz +. +Foo
+bar
+baz
+```````````````````````````````` + + +Authors who want interpretation 2 can put blank lines around +the thematic break, + +```````````````````````````````` example +Foo +bar + +--- + +baz +. +Foo +bar
++
baz
+```````````````````````````````` + + +or use a thematic break that cannot count as a [setext heading +underline], such as + +```````````````````````````````` example +Foo +bar +* * * +baz +. +Foo +bar
++
baz
+```````````````````````````````` + + +Authors who want interpretation 3 can use backslash escapes: + +```````````````````````````````` example +Foo +bar +\--- +baz +. +Foo +bar +--- +baz
+```````````````````````````````` + + +## Indented code blocks + +An [indented code block](@) is composed of one or more +[indented chunks] separated by blank lines. +An [indented chunk](@) is a sequence of non-blank lines, +each indented four or more spaces. The contents of the code block are +the literal contents of the lines, including trailing +[line endings], minus four spaces of indentation. +An indented code block has no [info string]. + +An indented code block cannot interrupt a paragraph, so there must be +a blank line between a paragraph and a following indented code block. +(A blank line is not needed, however, between a code block and a following +paragraph.) + +```````````````````````````````` example + a simple + indented code block +. +a simple
+ indented code block
+-
+
-
+
foo
+bar
+
+
-
+
-
+
foo
+-
+
- bar +
+
<a/>
+*hi*
+
+- one
+chunk1
+
+chunk2
+
+
+
+chunk3
+chunk1
+
+ chunk2
+Foo +bar
+```````````````````````````````` + + +However, any non-blank line with fewer than four leading spaces ends +the code block immediately. So a paragraph may occur immediately +after indented code: + +```````````````````````````````` example + foo +bar +. +foo
+bar
+```````````````````````````````` + + +And indented code can occur immediately before and after other kinds of +blocks: + +```````````````````````````````` example +# Heading + foo +Heading +------ + foo +---- +. +Heading
+foo
+Heading
+foo
++```````````````````````````````` + + +The first line can be indented more than four spaces: + +```````````````````````````````` example + foo + bar +. +
foo
+bar
+foo
+foo
+<
+ >
+<
+ >
+foo
aaa
+~~~
+aaa
+```
+aaa
+```
+aaa
+~~~
+
+```
+aaa
++++aaa +
bbb
+```````````````````````````````` + + +A code block can have all empty lines as its content: + +```````````````````````````````` example +``` + + +``` +. +
+
+aaa
+aaa
+aaa
+aaa
+aaa
+aaa
+ aaa
+aaa
+```
+aaa
+```
+aaa
+aaa
+aaa
+ ```
+
+aaa
aaa
+~~~ ~~
+foo
+bar
+baz
+```````````````````````````````` + + +Other blocks can also occur before and after fenced code blocks +without an intervening blank line: + +```````````````````````````````` example +foo +--- +~~~ +bar +~~~ +# baz +. +foo
+bar
+baz
+```````````````````````````````` + + +An [info string] can be provided after the opening code fence. +Although this spec doesn't mandate any particular treatment of +the info string, the first word is typically used to specify +the language of the code block. In HTML output, the language is +normally indicated by adding a class to the `code` element consisting +of `language-` followed by the language name. + +```````````````````````````````` example +```ruby +def foo(x) + return 3 +end +``` +. +def foo(x)
+ return 3
+end
+def foo(x)
+ return 3
+end
+aa
+foo
foo
+``` aaa
+` within a HTML block started by `
