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 the following software:

• Git for Windows
• [Chocolatey]

Install Chocolatey

We provide the following for your convenience. 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%.

Important: 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 [email protected]: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.
   

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