{"id":13707531,"url":"https://github.com/OpenMage/devdocs","last_synced_at":"2025-05-06T03:32:10.895Z","repository":{"id":44633538,"uuid":"265988482","full_name":"OpenMage/devdocs","owner":"OpenMage","description":"Developer Documentation","archived":false,"fork":false,"pushed_at":"2024-01-30T14:16:12.000Z","size":264311,"stargazers_count":7,"open_issues_count":8,"forks_count":12,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-04-30T21:28:00.202Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/OpenMage.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2020-05-22T01:18:54.000Z","updated_at":"2024-01-31T00:21:21.000Z","dependencies_parsed_at":"2024-04-21T20:11:01.121Z","dependency_job_id":null,"html_url":"https://github.com/OpenMage/devdocs","commit_stats":{"total_commits":14021,"total_committers":582,"mean_commits":24.09106529209622,"dds":0.8627059410883675,"last_synced_commit":"8a33d8045b454f1b7aa2b7dba8829d603a5a3d42"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenMage%2Fdevdocs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenMage%2Fdevdocs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenMage%2Fdevdocs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenMage%2Fdevdocs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/OpenMage","download_url":"https://codeload.github.com/OpenMage/devdocs/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252455725,"owners_count":21750515,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-02T22:01:34.392Z","updated_at":"2025-05-06T03:32:05.889Z","avatar_url":"https://github.com/OpenMage.png","language":"HTML","funding_links":[],"categories":["HTML"],"sub_categories":[],"readme":"# Magento Developer Documentation\n\nWelcome! This site contains the latest Magento developer documentation for ongoing Magento 2.x releases. For additional information, see our [Contribution Guide](https://github.com/OpenMage/devdocs/blob/master/.github/CONTRIBUTING.md).\n\n## Contributors\n\nOur 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.\n\n![](https://raw.githubusercontent.com/wiki/magento/magento2/images/dev_docs_contributors.png)\n\n# Building this site\n\nYou can build this site locally in the following ways:\n\n- [Installing the project dependencies locally](#build-using-jekyll) (Mac, Linux)\n- [Using a Docker container](#build-using-docker) (Mac, Linux)\n- [Using a Vagrant virtual machine](#build-using-vagrant) (Mac, Linux, Windows)\n- [Build DevDocs in Windows](#build-devdocs-in-windows) (Windows 7 \u0026 10)\n\n## Build using Jekyll\n\nFor local builds, you need to install Ruby 2.4 or later.\n\nTo check the Ruby version on your environment, run in your terminal:\n\n```shell\n$ ruby -v\n```\n\n### Install the latest Ruby (if the Ruby version is less than 2.4)\n\n**MacOS users**\n\n1. Install Homebrew. See the [Homebrew site](https://brew.sh) for instructions.\n1. Use Homebrew to install the latest stable version of Ruby:\n\n   ```\n   $ brew install ruby\n   ```\n\n**Unix, Windows and other OS users**\n\nSee the [Ruby site](https://www.ruby-lang.org/en/documentation/installation) for instructions.\n\n### Install Bundler\n\nInstall the [Bundler](https://bundler.io/) gem, which helps with Ruby dependencies:\n\n```\n$ gem install bundler\n```\n\nOnce you have completed preparing your environment, you can build locally and review the site in your browser.\n\n### Install devdocs\n\nClone or download the repository. The first time you are at the `devdocs` directory, run:\n\n```\n$ bundle install\n```\n\nOnce you have completed preparing your environment, you can build locally and review the site in your browser.\n\n### To build locally:\n\n#### Using rake\n\n[rake](https://github.com/ruby/rake) is a native Ruby tool that helps to automate tasks.\n\n1. Run the rake task that installs all required dependencies and starts the [Jekyll](https://jekyllrb.com/) server:\n\n   ```\n   $ rake preview\n   ```\n\n1. Press `Ctrl+C` in the serve terminal to stop the server.\n\nIf rake fails on your environment, generate the preview [using jekyll](#using-jekyll).\n\n#### Using jekyll\n\n1. 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:\n\n   ```\n   $ bundle install\n   ```\n\n1. To generate the local preview, run:\n\n   ```\n   $ bundle exec jekyll serve --incremental\n\n    Configuration file: /Users/username/Github/devdocs/_config.yml\n                Source: /Users/username/Github/devdocs\n           Destination: /Users/username/Github/devdocs/_site\n     Incremental build: enabled\n          Generating...\n                        done in x.x seconds.\n     Auto-regeneration: enabled for '/Users/username/Github/devdocs'\n        Server address: http://127.0.0.1:4000//\n      Server running... press ctrl-c to stop.\n   ```\n\n1. Use the **Server address** URL `http://127.0.0.1:4000/` in a browser to preview the content.\n\n1. Press `Ctrl+C` in the serve terminal to stop the server.\n\n\u003e ***TIP***\n\u003e 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.\n\n### To minimize build time locally:\n\n1. 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.\nThe following example will generate Magento 2.2 documentation only.\n\n   ```yaml\n    exclude:\n     - /community/\n     - /swagger/\n     - /vagrant/\n     - /guides/m1x/\n     - /guides/v2.0/\n     - /guides/v2.1/\n    # - /guides/v2.2/\n     - /guides/v2.3/\n\n    # Excluded in config.yml\n     - /scss/\n     - /bin/\n     - /node_modules/\n     - /vendor/\n     - /.*\n     - /Rakefile\n   ```\n\n1. Run the preview command:\n\n   ```\n   $ rake preview\n   ```\n   This command:\n   * Checks your environment according to the dependencies in `Gemfile.lock`.\n   * Removes the `_site/` directory, which contains previously generated preview files.\n   * Generates a new preview and opens the landing page in a web browsers.\n\nIf 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.\n\n## Build using Docker\n\nThis repository comes with the necessary configuration files for building a local copy of the Magento DevDocs with [Docker](https://docs.docker.com/), using [Docker Compose](https://docs.docker.com/compose/overview/).\n\nTo 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.\n\n### Docker for Mac\n\n- Refer [here](https://docs.docker.com/docker-for-mac/install/) for the official installation instructions.\n\n### Docker for Windows\n\n- Refer [here](https://docs.docker.com/docker-for-windows/install/) for the official installation instructions.\n\n### Docker Compose\n\n- Refer [here](https://docs.docker.com/compose/install/) for the official installation instructions.\n\n### Execution Steps\n\n1. Using [git](https://git-scm.com/), [clone](https://help.github.com/articles/cloning-a-repository/) this repository.\n2. Navigate to the resulting directory.\n3. Run `docker-compose up` to initialize the build process. Refer [here](https://docs.docker.com/compose/gettingstarted/#step-4-build-and-run-your-app-with-compose) for more details on the use of `docker-compose`.\n4. 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](https://github.com/OpenMage/devdocs/blob/develop/docker-compose.yml) file. If another port is desired, please refer [here](https://docs.docker.com/compose/compose-file/compose-file-v2/#ports) for further details regarding Docker Compose port mapping.\n\n### Addressing Problems With Docker Build\n\n1. Verify that the Docker engine is installed for the appropriate operating system.\n2. Verify that Docker Compose is installed.\n3. Verify that this repository has been cloned.\n4. Verify that the correct Docker Compose command(s) have been used in the same directory as the `docker-compose.yml` file.\n5. If there are still problems, please open an [Issue](https://help.github.com/articles/creating-an-issue/) on this repository.\n\n## Build using Vagrant\n\nYou can deploy the devdocs site locally using [this Vagrant project](https://github.com/magento-devdocs/vagrant-for-magento-devdocs).\n\n## Build DevDocs in Windows\n\nSome of the technologies we use to develop DevDocs is not compatible with Windows, such as [Jekyll](https://jekyllrb.com/docs/windows/). 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. \n\nDownload software:\n\n-  [Git for Windows](https://gitforwindows.org)\n-  [Chocolatey](https://chocolatey.org/install)\n\n### Install Chocolatey\n\nOnly Administrators can use Chocolatey features. You can use the Administrator account, or you can use the \"Run as Administrator\" function on the shortcut menu.\n\n1.  Open the **Command Prompt** using **Run as Administrator** in the shortcut menu.\n\n1.  [Install Chocolatey](https://chocolatey.org/install).\n\n    ```cmd\n    @\"%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'))\" \u0026\u0026 SET \"PATH=%PATH%;%ALLUSERSPROFILE%\\chocolatey\\bin\"\n    ```\n\n1.  Verify Chocolatey was added to the environment variables:\n\n    -  In the Windows UI, open search and type `path`.\n    -  In the Windows CMD console, type `echo %path%`.\n    \n    You should see `C:\\ProgramData\\chocolatey\\bin` in the path.\n\n1.  Close and reopen the command prompt before using `choco` commands.\n\nAfter 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.\n\n#### Install Ruby extension\n\nIf you have Ruby installed on the workstation, then you can skip this installation.\n\n1.  Open the **Command Prompt** using **Run as Administrator** in the shortcut menu.\n\n1.  Install the ruby extension:\n\n    ```cmd\n    choco install ruby\n    ```\n\n1.  Verify the environment variables were added properly:\n\n    -  In the Windows UI, open search and type `path`.\n    -  In the Windows CMD console, type `echo %path%`.\n\n\u003e  **NOTE**  \n\u003e  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.\n\n### Install Git for Windows\n\nUse 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.\n\nOpen the Git Setup file downloaded from the Git for Windows site and use the following settings during installation wizard:\n\n-  select **Use Git from Git Bash only**\n-  select **Checkout as-is, commit Unix-style line endings**\n-  select your preferred editor (can use Nano, Notepad++, or VIM)\n-  select **Enable symbolic links**\n\nAlthough you can install Git using Chocolatey, we chose to install _Git for Windows_ independently for more control of the installation settings.\n\n#### Set up SSH key\n\n1.  Open Git Bash. The **Git Bash** executable is on the shortcut menu.\n\n1.  Create a working directory for your Git repositories and change to the new directory.\n\n    ```bash\n    mkdir \u003cdirectory-name\u003e\n    ```\n\n1.  Follow the [Generating a new SSH](https://help.github.com/articles/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent/) instructions.\n\n\n### Clone and build the DevDocs repository\n\nYou may have to close and reopen the Git Bash application after the Choco installations.\n\n1.  Open Git Bash. The **Git Bash** executable is on the shortcut menu.\n\n1.  Change to the directory you created for Git repositories and clone the DevDocs repository.\n\n    ```bash\n    git clone git@github.com:OpenMage/devdocs.git\n    ```\n\n1.  Change to the `devdocs` directory.\n\n1.  Install [Bundler](https://bundler.io).\n\n    ```bash\n    gem install bundle\n    ```\n\n1.  Install gem executables required for building the site.\n\n    ```bash\n    bundle install\n    ```\n\n1.  Build site.\n\n    ```bash\n    bundle exec jekyll serve\n    ```\n\n    ```terminal\n    Configuration file: C:/Users/Administrator/mage/devdocs/_config.yml\n                Source: C:/Users/Administrator/mage/devdocs\n           Destination: C:/Users/Administrator/mage/devdocs/_site\n     Incremental build: disabled. Enable with --incremental\n          Generating...\n                        done in 643.551 seconds.\n     Auto-regeneration: enabled for 'C:/Users/Administrator/mage/devdocs'\n        Server address: http://127.0.0.1:4000/\n      Server running... press ctrl-c to stop.\n    ```\n\n\u003e  **NOTE**  \n\u003e  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.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FOpenMage%2Fdevdocs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FOpenMage%2Fdevdocs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FOpenMage%2Fdevdocs/lists"}