Using generate_exclude.rb Script

Due to the large amount of articles in our documentation, Jekyll builds the site quite slowly.

Normally, using the exclude property in the _config.yml file, Jekyll can exclude some of the folders.

exclude: [README.md,Gemfile,Gemfile.lock,deploy.sh,LICENSE,SlugLog.log,UrlMappings-and-conversion-logs/*,temp_exclude_result.tmp,generate_exlude.rb]

Using the generate_exclude.rb script (located in the ajax-docs repository) you can generate the array for the exclude property.

Important: Running the script will always checkout the changes in the _config.yml file. If you have any important changes, you should first create a backup.

Example 1: Generating an exclude array that will build only the general-information and controls/button folders.

ruby generate_exclude.rb "general-information" "controls/button"

The command above will:

1. checkout the _config.yml file;

2. read the passed arguments (unlimited number of paths can be passed);

3. parse the original exclude array from the _config.yml file;

4. find all child folders in the root;

5. find all child folders in the controls folder;

6. build the array to be used in the _config.yml file;

7. open notepad with the array as string, letting you to copy it.

   Note that you should manually copy the text from notepad and paste/set it as value to the exclude property in the _config.yml file.

8. after closing notepad, temp file will be removed and the script will stop.

The following snapshots illustrate in steps how to use the script:

Figure 1: Running the generate_exclude.rb script.

Figure 2: Copying the generated array.

Figure 3: Modifying the _config.yml file.

Figure 4: Closing Notepad to terminate the generate_exclude.rb script.

Figure 5: Running Jekyll with the excluded paths.

Figure 6: Browsing the generated documentation site.

Using the Watch feature of the script

The script provides a more advanced feature to run a watch process over the folders chosen to build.

This is done via additional --watch parameter at the end of the command.

ruby generate_exclude.rb "general-information" "controls/button" --watch

Note that with this option the configuration and the build are automatic.

Important: It is best to use a deployed to IIS site for easier usage. If you rather want to use Jekyll server:

1. run the script with the --watch option (do not close the console);

2. open a new console and run the server;

      jekyll serve
   

3. now, the first console serves the watch and the second runs the Jekyll server.

Using this options you should leave the console open. Any modification to the files, inside the chosen folders will cause a new Jekyll build automatically, and thus, let you to only refresh your browser and see the changes made.

Tip: To optimize even further your workflow, you can install and use the LiveReload plugin. When configured to observe the _site folder, changes will refresh your browser automatically.