Magento Developer Documentation
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github Sentence edit for contributing Oct 25, 2018
_data toc exclude fix Dec 12, 2018
_includes Fixed issue#3399 (#3443) Dec 12, 2018
_layouts Increase contrast in Redoc a little bit Nov 8, 2018
_plugins Excluded 'redirect.html' to decrease generation time Dec 12, 2018
_videos Fix add-a-javascript-module path to frontend Oct 15, 2018
bin Add jekyll binstub Jul 27, 2015
codelinks Removed globally frontmatter params: 'version', 'layout: default', 'g… Aug 15, 2018
common Updates to Fastly WAF docs (#3272) Dec 5, 2018
community/resources Add link to community resources Dec 4, 2018
guides Added new mixin file (#3444) Dec 12, 2018
i MAGECLOUD-2027 New look for Cloud release notes (#3336) Nov 21, 2018
js Consolidate devdocs and engcomm contributors/maintainers (#2074) Aug 17, 2018
mftf Fixed broken links Dec 10, 2018
rakelib Editorial changes Nov 20, 2018
redoc/2.3 Enable response samples in JSON format Nov 6, 2018
schemas first draft of REST docs Oct 8, 2015
scss MAGECLOUD-2027 New look for Cloud release notes (#3336) Nov 21, 2018
swagger Fix the link to Magento logo Oct 18, 2018
.gitignore Set up 'url' for staging in a separate config Nov 14, 2018
404.md MAGEDOC-3095: Fix broken link on 404 page Aug 3, 2018
Gemfile Removed jekyll-last-modified-at; updated all gems dependencies Dec 10, 2018
Gemfile.lock Removed jekyll-last-modified-at; updated all gems dependencies Dec 10, 2018
README.md Fixed links in README Oct 21, 2018
Rakefile Change Jekyll namespace to JekyllRake Nov 14, 2018
_config.checks.yml Update _config.checks.yml Nov 28, 2018
_config.prod.yml Add production config Oct 3, 2018
_config.stage.yml Set up 'url' for staging in a separate config Nov 14, 2018
_config.yml Added a custom plugin with hook that generates last_modified_at attri… Dec 7, 2018
availability.md MAGEDOC-3276: Updated product availability (#3387) Nov 30, 2018
favicon.ico Correct Favicon Jun 13, 2015
feed.xml MAGEDOC-3040: Improve load time Jul 9, 2018
gulpfile.js Merge branch 'develop' of https://github.com/magento/devdocs_internal Apr 30, 2018
index.html MAGEDOC-2809 Move 2.3 index.html into root Nov 27, 2018
magento-techbull.md Fix broken links to tech bulletins Nov 20, 2018
magento-third-party.md Removed globally frontmatter params: 'version', 'layout: default', 'g… Aug 15, 2018
package-lock.json Bd conversion (#2789) Aug 22, 2018
package.json Merge branch 'develop' of https://github.com/magento/devdocs_internal Apr 30, 2018
robots.txt Add absolute url to sitemap Dec 5, 2018
search.md Removed globally frontmatter params: 'version', 'layout: default', 'g… Aug 15, 2018
system-requirements.md Updated links in system-requirements Oct 21, 2018
videos.html Videos section organization Jan 12, 2017
whats-new.md Added devdocs updates for the passed week Dec 11, 2018

README.md

Magento Developer Documentation

Welcome! This site contains the latest Magento developer documentation for ongoing Magento 2.x releases. For additional information, see our Contribution Guide.

Contributors

Our goal is to provide the Magento community with comprehensive and quality technical documentation. We believe that to accomplish that goal we need experts from the community to share their knowledge with us and each other. We are thankful to all of our contributors for improving Magento documentation.

Building this site

You can build this site locally in the following ways:

Build using Jekyll

For local builds, you need to install Ruby 2.4 or later.

To check the Ruby version on your environment, run in your terminal:

$ ruby -v

Install the latest Ruby (if the Ruby version is less than 2.4)

MacOS users

  1. Install Homebrew. See the Homebrew site for instructions.

  2. Use Homebrew to install the latest stable version of Ruby:

    $ brew install ruby
    

Unix, Windows and other OS users

See the Ruby site for instructions.

Install Bundler

Install the Bundler gem, which helps with Ruby dependencies:

$ gem install bundler

Once you have completed preparing your environment, you can build locally and review the site in your browser.

Install devdocs

Clone or download the repository. The first time you are at the devdocs directory, run:

$ bundle install

Once you have completed preparing your environment, you can build locally and review the site in your browser.

To build locally:

Using rake

rake is a native Ruby tool that helps to automate tasks.

  1. Run the rake task that installs all required dependencies and starts the Jekyll server:

    $ rake preview
    
  2. Press Ctrl+C in the serve terminal to stop the server.

If rake fails on your environment, generate the preview using jekyll.

Using jekyll

  1. The first time you are at the devdocs directory or when you need to pick up changes in Gemfile.lock dependencies (for example, theme changes), run:

    $ bundle install
    
  2. To generate the local preview, run:

    $ bundle exec jekyll serve --incremental
    
     Configuration file: /Users/username/Github/devdocs/_config.yml
                 Source: /Users/username/Github/devdocs
            Destination: /Users/username/Github/devdocs/_site
      Incremental build: enabled
           Generating...
                         done in x.x seconds.
      Auto-regeneration: enabled for '/Users/username/Github/devdocs'
         Server address: http://127.0.0.1:4000//
       Server running... press ctrl-c to stop.
    
  3. Use the Server address URL http://127.0.0.1:4000/ in a browser to preview the content.

  4. Press Ctrl+C in the serve terminal to stop the server.

TIP Leave the serve terminal open and running. Every time you save changes to a file, it automatically regenerates the site so you can test the output immediately. Changing the _config.yml file requires a fresh build. Using the --incremental option limits re-builds to posts and pages that have changed.

To minimize build time locally:

  1. Create a _config.local.yml file at the root of the project directory and exclude all versions except the one that you want to preview. The following example will generate Magento 2.2 documentation only.

     exclude:
      - /community/
      - /swagger/
      - /vagrant/
      - /guides/m1x/
      - /guides/v2.0/
      - /guides/v2.1/
     # - /guides/v2.2/
      - /guides/v2.3/
    
     # Excluded in config.yml
      - /scss/
      - /bin/
      - /node_modules/
      - /vendor/
      - /.*
      - /Rakefile
  2. Run the preview command:

    $ rake preview
    

    This command:

    • Checks your environment according to the dependencies in Gemfile.lock.
    • Removes the _site/ directory, which contains previously generated preview files.
    • Generates a new preview and opens the landing page in a web browsers.

If you don't have the _config.local.yml file at the root of your devdocs/ directory, the rake will generate all versions of the documentation.

Build using Docker

This repository comes with the necessary configuration files for building a local copy of the Magento DevDocs with Docker, using Docker Compose.

To use Docker and Docker Compose, first download and install Docker for the appropriate operating system, and then install Docker Compose to execute the docker-compose.yml configuration file.

Docker for Mac

  • Refer here for the official installation instructions.

Docker for Windows

  • Refer here for the official installation instructions.

Docker Compose

  • Refer here for the official installation instructions.

Execution Steps

  1. Using git, clone this repository.
  2. Navigate to the resulting directory.
  3. Run docker-compose up to initialize the build process. Refer here for more details on the use of docker-compose.
  4. Visit http://localhost:4000/ in a web browser, and you should be presented with a local copy of the Magento DevDocs. The configuration for the local port (4000 by default) is found in the docker-compose.yml file. If another port is desired, please refer here for further details regarding Docker Compose port mapping.

Addressing Problems With Docker Build

  1. Verify that the Docker engine is installed for the appropriate operating system.
  2. Verify that Docker Compose is installed.
  3. Verify that this repository has been cloned.
  4. Verify that the correct Docker Compose command(s) have been used in the same directory as the docker-compose.yml file.
  5. If there are still problems, please open an Issue on this repository.

Build using Vagrant

You can deploy the devdocs site locally using this Vagrant project.


If you have questions, open an issue and ask us. We're looking forward to hearing from you!

Build DevDocs in Windows

Some of the technologies we use to develop DevDocs is not compatible with Windows, such as Jekyll. For this reason, we do not support DevDocs management in Windows; however, we have documented the following procedures to build the DevDocs in a Windows environment. Any further use of this setup or troubleshooting is up to you.

Download software:

Install Chocolatey

Only Administrators can use Chocolatey features. You can use the Administrator account, or you can use the "Run as Administrator" function on the shortcut menu.

  1. Open the Command Prompt using Run as Administrator in the shortcut menu.

  2. Install Chocolatey.

    @"%SystemRoot%\System32\WindowsPowerShell\v1.0\powershell.exe" -NoProfile -InputFormat None -ExecutionPolicy Bypass -Command "iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1'))" && SET "PATH=%PATH%;%ALLUSERSPROFILE%\chocolatey\bin"
  3. Verify Chocolatey was added to the environment variables:

    • In the Windows UI, open search and type path.
    • In the Windows CMD console, type echo %path%.

    You should see C:\ProgramData\chocolatey\bin in the path.

  4. Close and reopen the command prompt before using choco commands.

After running the script at the command line, you can install any required extensions. Chocolately has many extensions available, similar to Homebrew for MacOS. As a best practice, only use extensions labeled as a "trusted package". You can install editors, such as Nano and Notepad++, using Chocolatey, as well.

Install Ruby extension

If you have Ruby installed on the workstation, then you can skip this installation.

  1. Open the Command Prompt using Run as Administrator in the shortcut menu.

  2. Install the ruby extension:

    choco install ruby
  3. Verify the environment variables were added properly:

    • In the Windows UI, open search and type path.
    • In the Windows CMD console, type echo %path%.

NOTE
If you encounter problems with Ruby, or the gem command is not recognized, you can install the rubyinstaller-devkit.exe development kit located in the c:\ProgramData\chocolatey\bin folder.

Install Git for Windows

Use Git for Windows to prevent interference with the existing Windows environment and to have Git Bash and Git GUI launch commands available on the shortcut menu.

Open the Git Setup file downloaded from the Git for Windows site and use the following settings during installation wizard:

  • select Use Git from Git Bash only
  • select Checkout as-is, commit Unix-style line endings
  • select your preferred editor (can use Nano, Notepad++, or VIM)
  • select Enable symbolic links

Although you can install Git using Chocolatey, we chose to install Git for Windows independently for more control of the installation settings.

Set up SSH key

  1. Open Git Bash. The Git Bash executable is on the shortcut menu.

  2. Create a working directory for your Git repositories and change to the new directory.

    mkdir <directory-name>
  3. Follow the Generating a new SSH instructions.

Clone and build the DevDocs repository

You may have to close and reopen the Git Bash application after the Choco installations.

  1. Open Git Bash. The Git Bash executable is on the shortcut menu.

  2. Change to the directory you created for Git repositories and clone the DevDocs repository.

    git clone git@github.com:magento/devdocs.git
  3. Change to the devdocs directory.

  4. Install Bundler.

    gem install bundle
  5. Install gem executables required for building the site.

    bundle install
  6. Build site.

    bundle exec jekyll serve
    Configuration file: C:/Users/Administrator/mage/devdocs/_config.yml
                Source: C:/Users/Administrator/mage/devdocs
           Destination: C:/Users/Administrator/mage/devdocs/_site
     Incremental build: disabled. Enable with --incremental
          Generating...
                        done in 643.551 seconds.
     Auto-regeneration: enabled for 'C:/Users/Administrator/mage/devdocs'
        Server address: http://127.0.0.1:4000/
      Server running... press ctrl-c to stop.
    

NOTE
The .bash_profile file CAN be created and managed using Git Bash, which is useful for aliases and other customizations, This file is in the users/Administrator folder.