Merge pull request #2 from magento/master

sync with upstream

Author: snowcore

.github/CONTRIBUTING.md

@@ -66,19 +66,8 @@ The following guidelines may answer most of your questions and help you get star
 - Familiarize yourself with the organization and conventions of our existing documentation before creating a pull request. Changes that are consistent with our style and conventions have a higher acceptance rate.
 
     - If you need to update the site navigation, ask for help in Slack ([#devdocs](https://magentocommeng.slack.com/messages/CAN932A3H)).
-    - We use symbolic links for topics that are the same across versions of Magento. Remove the symbolic link and add a new file if your changes are unique to a specific version. Copy and paste a previous version of the topic to get started.
 
-        For example:
-
-        ```bash
-        git rm guides/v2.2/install-gde/composer.md
-        ```
-
-        ```bash
-        cp guides/v2.1/install-gde/composer.md guides/v2.2/install-gde/composer.md
-        ```
-
-- Make sure that you update the correct version(s) of documentation (v2.1, v2.2, v2.3). If you are not sure what directory to put your content in, just do your best. We can help re-locate it (if necessary) during the review process.
+- Ensure that you update the correct version(s) of documentation (v2.2, v2.3). If you are not sure what directory to put your content in, just do your best. We can help re-locate it (if necessary) during the review process.
 - Review your work for basic typos, formatting errors, or ambiguous sentences before opening a pull request.
 - Revise pull requests according to review feedback. We will close pull requests that require an inordinate amount of time to review and process (especially for minor changes) if you fail to make revisions according to review feedback.
 - Do not directly contact DevDocs team members or maintainers on Slack to review your pull request unless it has been open for more than five days. We have a process and queue for pull requests that everyone must follow.
@@ -105,17 +94,18 @@ _(Optional)_ To review your changes in HTML output, follow the instructions in t
 
 We provide templates to help you get started writing new content and understanding Markdown formatting:
 
-- **General topic template** - [Markdown](https://github.com/magento/devdocs/blob/master/guides/v2.1/contributor-guide/templates/basic_template.md) | [HTML](https://devdocs.magento.com/guides/v2.3/contributor-guide/templates/basic_template.html): This is a template for writing any topic with example formats and styles.
+- **General topic template** - [Markdown](https://github.com/magento/devdocs/blob/master/guides/v2.3/contributor-guide/templates/basic_template.md) | [HTML](https://devdocs.magento.com/guides/v2.3/contributor-guide/templates/basic_template.html): This is a template for writing any topic with example formats and styles.
 - **Tutorial templates**: These templates provide example formats and styles for step-by-step instructions (like how-tos). Each file adds navigation buttons when content is generated. Templates include:
-  - First introduction topic - [Markdown](https://github.com/magento/devdocs/blob/master/guides/v2.1/contributor-guide/templates/tutorial-template-first.md) | [HTML](https://devdocs.magento.com/guides/v2.3/contributor-guide/templates/tutorial-template-first.html): Introduction to a tutorial for prerequisites and listing steps
-  - Middle topic - [Markdown](https://github.com/magento/devdocs/blob/master/guides/v2.1/contributor-guide/templates/tutorial-template-middle.md) |  [HTML](https://devdocs.magento.com/guides/v2.3/contributor-guide/templates/tutorial-template-middle.html): Use for each step in a tutorial.
-  - Final step topic - [Markdown](https://github.com/magento/devdocs/blob/master/guides/v2.1/contributor-guide/templates/tutorial-template-last.md) | [HTML](https://devdocs.magento.com/guides/v2.3/contributor-guide/templates/tutorial-template-last.html): Use for the last step of the tutorial.
+  - First introduction topic - [Markdown](https://github.com/magento/devdocs/blob/master/guides/v2.3/contributor-guide/templates/tutorial-template-first.md) | [HTML](https://devdocs.magento.com/guides/v2.3/contributor-guide/templates/tutorial-template-first.html): Introduction to a tutorial for prerequisites and listing steps
+  - Middle topic - [Markdown](https://github.com/magento/devdocs/blob/master/guides/v2.3/contributor-guide/templates/tutorial-template-middle.md) |  [HTML](https://devdocs.magento.com/guides/v2.3/contributor-guide/templates/tutorial-template-middle.html): Use for each step in a tutorial.
+  - Final step topic - [Markdown](https://github.com/magento/devdocs/blob/master/guides/v2.3/contributor-guide/templates/tutorial-template-last.md) | [HTML](https://devdocs.magento.com/guides/v2.3/contributor-guide/templates/tutorial-template-last.html): Use for the last step of the tutorial.
 
 ### Edit metadata
 
 The Markdown (.md) file's metadata is a set of YAML key-value pairs. The metadata section is located at the top of each file. For more info, see the [Basic Template](https://devdocs.magento.com/guides/v2.3/contributor-guide/templates/basic_template.html).
 
 ```yaml
+
 ---
 group: install2
 title: Continue with your installation
@@ -129,6 +119,45 @@ title: Continue with your installation
 | `group`       | Defines the topic's guide or section. Use the table of contents `.yml` file name. This loads your left-side navigation. We will help during the PR process to add new files to the `.yml` file. |
 | `title`       | Sets the title of the page in the HTML metadata and the main title on the page.  |
 
+## Symbolic links
+
+We use symbolic links for topics that are the same across versions of Magento. A file is symlinked if the entire content of the file is a path to the original version, such as [ext-best-practices/tutorials/serialized-to-json-data-upgrade.md](https://github.com/magento/devdocs/blob/master/guides/v2.3/ext-best-practices/tutorials/serialized-to-json-data-upgrade.md). Note that some editors will automatically follow symlinks so it might not be clear if a file is symlinked or not. Check the file on Github directly to be sure.
+
+### Create a symbolic link
+
+When you create a new topic (create a new `.md` file) and its content is the same for 2.2 and 2.3 versions, create a symbolic link.
+
+For example, if you created a new file for v.2.2---`guides/v2.2/install-gde/new-doc-topic.md`---and its content is the same for v.2.3, use the command below to create the symbolic link.
+
+```bash
+cd <DEVDOCS_REPOSITORY_ROOT_DIR>
+```
+
+```bash
+ln -s guides/v2.2/install-gde/new-doc-topic.md guides/v2.3/install-gde/new-doc-topic.md
+```
+
+If you have an image that is identical between versions, it is should placed in `/common/images`. Please optimize images before committing them to the repository.
+If done correctly, the symbolic link path will start with 3 or 4 instances of `../`, as the above example shows.
+
+### Remove a symbolic link
+
+If your changes are unique to a specific version, remove the symbolic link and add a new file. Copy and paste a previous version of the topic to get started.
+
+The removal should use the `git rm` command specifically. Deleting the file through the regular file system might cause issues with the repository.
+
+For example:
+
+```bash
+git rm guides/v2.3/install-gde/composer.md
+```
+
+```bash
+cp guides/v2.2/install-gde/composer.md guides/v2.3/install-gde/composer.md
+```
+
+Once you have the copy in place, you can edit it with the version-specific information.
+
 ## Report an issue
 
 If you find a typo or errors in Magento DevDocs, you can either fix it with a pull request (as described above) or you can report it by creating an issue in the DevDocs GitHub repository.

.github/ISSUE_TEMPLATE/COMMUNITY_ISSUE_TEMPLATE.md

@@ -8,6 +8,7 @@ about: Create an issue related to a community engineering effort
 <!-- (REQUIRED) Provide information for the doc request including any Community code issues or PRs, Magento versions, or devdoc pages. -->
 
 Type of Doc:
+
 - [ ] New topic
 - [ ] Topic Update, Devdoc link:
 - [ ] Other
@@ -17,13 +18,15 @@ Magento 2 GitHub Issue: https://github.com/magento/devdocs/issues/link
 Magento 2 GitHub PR: https://github.com/magento/devdocs/pull/link
 
 Magento 2 version:
+
 - [ ] 2.1.X
 - [ ] 2.2.X
 - [ ] 2.3.X
 - [ ] back port
 - [ ] forward port
 
 Notifications of Changes:
+
 - [ ] Changes to Admin interface?
 - [ ] New software requirements?
 - [ ] New REST endpoints or updated GraphQL query syntax?
@@ -37,7 +40,6 @@ Notifications of Changes:
 
 <!-- (OPTIONAL) What other information can you provide? -->
 
-
 <!--
 Thank you for taking the time to request updates for your Community Engineering contribution!
 GitHub Issues should only be created for problems/topics related to this project's codebase.

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,24 +1,20 @@
 ## Purpose of this pull request
 
-<!-- REQUIRED Describe the goal and the type of changes this pull request covers. -->
-
 This pull request (PR) ...
 
 ## Affected DevDocs pages
 
 <!-- REQUIRED List the affected pages on devdocs.magento.com (URLs). Not needed for large numbers of files. -->
 
-- ...
 - ...
 
 ## Links to Magento source code
 
 <!--  OPTIONAL - REMOVE THIS SECTION IF NOT USED. If this pull request references a file in a Magento codebase repository, add it here. -->
 
-- ...
 - ...
 
-<!-- 
+<!--
 If you are fixing a GitHub issue, note it using GitHub keyword format (https://help.github.com/en/articles/closing-issues-using-keywords#closing-an-issue-in-a-different-repository) to close the issue when this pull request is merged. Example: `Fixes #1234`
 
 `master` is the default branch. Merged pull requests to `master` go live on the site automatically. Any requested changes to content on the `master` branch must be related to the released codebase. Any content related to future releases goes in the `develop` branch.

.gitignore

@@ -33,3 +33,4 @@ _algolia_api_key
 ###################################
 
 /guides/v2.0/
+/guides/v2.1/

.mdlrc

@@ -0,0 +1,2 @@
+style '_checks/styles/style-rules-dev'
+ignore_front_matter true

404.md

@@ -12,8 +12,6 @@ permalink: /404.html
 
 The page you are looking for could not be found or the documentation does not exist.
 
-
 To report a missing page, please submit an issue in our public [GitHub](https://github.com/magento/devdocs) repo.
 
-
 [Return to main page]({{ site.baseurl }}/)

Docfile.yml

@@ -17,7 +17,7 @@ content_map:
 -
   directory: page-builder
   repository: magento/magento2-page-builder
-  branch: 1.0-develop
+  branch: 1.1-develop
   filter: true
 -
   directory: page-builder-migration

Gemfile

@@ -10,6 +10,7 @@ gem 'wdm', platform: :mswin
 
 group :test do
   gem 'html-proofer'
+  gem 'mdl'
   gem 'launchy'
 end
 

Gemfile.lock

@@ -1,28 +1,22 @@
 GIT
   remote: https://github.com/magento-devdocs/devdocs-theme.git
-  revision: 450a470aa4b937400190d009131fa91cf27d7a9d
+  revision: 84a3ed7f0df264a2c2086167efbd7d0545d329c4
   specs:
-    devdocs (0.0.1)
+    devdocs (4)
       jekyll (>= 3.3)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    activesupport (5.2.3)
-      concurrent-ruby (~> 1.0, >= 1.0.2)
-      i18n (>= 0.7, < 2)
-      minitest (~> 5.1)
-      tzinfo (~> 1.1)
-    addressable (2.6.0)
-      public_suffix (>= 2.0.2, < 4.0)
-    algolia_html_extractor (2.6.1)
+    addressable (2.7.0)
+      public_suffix (>= 2.0.2, < 5.0)
+    algolia_html_extractor (2.6.2)
       json (~> 2.0)
-      nokogiri (~> 1.8.2)
-    algoliasearch (1.26.0)
+      nokogiri (~> 1.10.4)
+    algoliasearch (1.27.0)
       httpclient (~> 2.8, >= 2.8.3)
       json (>= 1.5.1)
     colorator (1.1.0)
-    colorize (0.8.1)
     concurrent-ruby (1.1.5)
     em-websocket (0.5.1)
       eventmachine (>= 0.12.9)
@@ -33,35 +27,34 @@ GEM
     exifr (1.3.6)
     faraday (0.15.4)
       multipart-post (>= 1.2, < 3)
-    ffi (1.10.0)
+    ffi (1.11.1)
     filesize (0.2.0)
     forwardable-extended (2.6.0)
-    fspath (3.1.0)
-    html-proofer (3.9.3)
-      activesupport (>= 4.2, < 6.0)
+    fspath (3.1.2)
+    html-proofer (3.12.2)
       addressable (~> 2.3)
-      colorize (~> 0.8)
-      mercenary (~> 0.3.2)
-      nokogiri (~> 1.8.1)
+      mercenary (~> 0.3)
+      nokogiri (~> 1.10)
       parallel (~> 1.3)
+      rainbow (~> 3.0)
       typhoeus (~> 1.3)
       yell (~> 2.0)
     http_parser.rb (0.6.0)
     httpclient (2.8.3)
     i18n (0.9.5)
       concurrent-ruby (~> 1.0)
-    image_optim (0.26.3)
+    image_optim (0.26.5)
       exifr (~> 1.2, >= 1.2.2)
       fspath (~> 3.0)
       image_size (>= 1.5, < 3)
       in_threads (~> 1.3)
       progress (~> 3.0, >= 3.0.1)
-    image_optim_pack (0.5.2.20190428)
+    image_optim_pack (0.6.0)
       fspath (>= 2.1, < 4)
       image_optim (~> 0.19)
-    image_size (2.0.1)
-    in_threads (1.5.1)
-    jekyll (3.8.5)
+    image_size (2.0.2)
+    in_threads (1.5.3)
+    jekyll (3.8.6)
       addressable (~> 2.4)
       colorator (~> 1.0)
       em-websocket (~> 0.5)
@@ -74,11 +67,11 @@ GEM
       pathutil (~> 0.9)
       rouge (>= 1.7, < 4)
       safe_yaml (~> 1.0)
-    jekyll-algolia (1.4.11)
+    jekyll-algolia (1.5.0)
       algolia_html_extractor (~> 2.6)
-      algoliasearch (~> 1.25)
+      algoliasearch (~> 1.26)
       filesize (~> 0.1)
-      jekyll (~> 3.0)
+      jekyll (>= 3.6, < 5.0)
       json (~> 2.0)
       nokogiri (~> 1.6)
       progressbar (~> 1.9)
@@ -106,28 +99,35 @@ GEM
       rb-fsevent (~> 0.9, >= 0.9.4)
       rb-inotify (~> 0.9, >= 0.9.7)
       ruby_dep (~> 1.2)
+    mdl (0.5.0)
+      kramdown (~> 1.12, >= 1.12.0)
+      mixlib-cli (~> 1.7, >= 1.7.0)
+      mixlib-config (~> 2.2, >= 2.2.1)
     mercenary (0.3.6)
-    mini_portile2 (2.3.0)
-    minitest (5.11.3)
+    mini_portile2 (2.4.0)
+    mixlib-cli (1.7.0)
+    mixlib-config (2.2.18)
+      tomlrb
     multipart-post (2.1.1)
     netrc (0.11.0)
-    nokogiri (1.8.5)
-      mini_portile2 (~> 2.3.0)
+    nokogiri (1.10.4)
+      mini_portile2 (~> 2.4.0)
     octokit (4.14.0)
       sawyer (~> 0.8.0, >= 0.5.3)
     parallel (1.17.0)
     pathutil (0.16.2)
       forwardable-extended (~> 2.6)
-    progress (3.5.0)
-    progressbar (1.10.0)
-    public_suffix (3.0.3)
+    progress (3.5.2)
+    progressbar (1.10.1)
+    public_suffix (4.0.1)
+    rainbow (3.0.0)
     rb-fsevent (0.10.3)
     rb-inotify (0.10.0)
       ffi (~> 1.0)
-    rouge (3.3.0)
+    rouge (3.11.0)
     ruby_dep (1.5.0)
     safe_yaml (1.0.5)
-    sass (3.7.3)
+    sass (3.7.4)
       sass-listen (~> 4.0.0)
     sass-listen (4.0.0)
       rb-fsevent (~> 0.9, >= 0.9.4)
@@ -136,18 +136,16 @@ GEM
       addressable (>= 2.3.5)
       faraday (> 0.8, < 2.0)
     thor (0.20.3)
-    thread_safe (0.3.6)
+    tomlrb (1.2.8)
     typhoeus (1.3.1)
       ethon (>= 0.9.0)
-    tzinfo (1.2.5)
-      thread_safe (~> 0.1)
     verbal_expressions (0.1.5)
     wdm (0.1.1)
     whatsup_github (0.0.1)
       netrc (~> 0.10)
       octokit (~> 4.14)
       thor (~> 0.20)
-    yell (2.1.0)
+    yell (2.2.0)
 
 PLATFORMS
   ruby
@@ -166,6 +164,7 @@ DEPENDENCIES
   jekyll-sitemap
   jekyll-titles-from-headings
   launchy
+  mdl
   wdm
   whatsup_github