From d1093e0160e95fb4253304ba145f4a44fa3a8f9b Mon Sep 17 00:00:00 2001 From: Ashwin Maroli Date: Wed, 9 Sep 2020 14:48:20 +0530 Subject: [PATCH] Improve maintainability of config option data (#8383) Merge pull request 8383 --- docs/_data/config_options.yml | 183 --------------------------- docs/_data/config_options/build.yml | 110 ++++++++++++++++ docs/_data/config_options/global.yml | 77 +++++++++++ docs/_data/config_options/serve.yml | 71 +++++++++++ docs/_docs/configuration/options.md | 16 +-- 5 files changed, 266 insertions(+), 191 deletions(-) delete mode 100644 docs/_data/config_options.yml create mode 100644 docs/_data/config_options/build.yml create mode 100644 docs/_data/config_options/global.yml create mode 100644 docs/_data/config_options/serve.yml diff --git a/docs/_data/config_options.yml b/docs/_data/config_options.yml deleted file mode 100644 index 5bc8330d..00000000 --- a/docs/_data/config_options.yml +++ /dev/null @@ -1,183 +0,0 @@ -global: -- name: Site Source - description: Change the directory where Jekyll will read files - option: "source: DIR" - flag: -s, --source DIR -- name: Site Destination - description: Change the directory where Jekyll will write files - option: "destination: DIR" - flag: -d, --destination DIR -- name: Safe - description: "Disable non-whitelisted plugins, caching to disk, and ignore symbolic links." - option: "safe: BOOL" - flag: --safe -- name: Disable Disk Cache - version-badge: 4.1.0 - description: "Disable caching of content to disk in order to skip creating a .jekyll-cache or similar directory at the source to avoid interference with virtual environments and third-party directory watchers. Caching to disk is always disabled in safe mode." - option: "disable_disk_cache: BOOL" - flag: --disable-disk-cache -- name: Ignore theme configuration - version-badge: 4.1.0 - description: "Jekyll 4.0 started allowing themes to bundle a _config.yml to simplify theme-onboarding for new users. In the unfortunate situation that importing a bundled theme configuration messes up the merged site-configuration, the user can configure Jekyll to not import the theme-config entirely." - option: "ignore_theme_config: BOOL" -- name: Exclude - description: "Exclude directories and/or files from the conversion. These exclusions are relative to the site's source directory and cannot be outside the source directory." - option: "exclude: [DIR, FILE, ...]" -- name: Include - description: "Force inclusion of directories and/or files in the conversion. .htaccess is a good example since dotfiles are excluded by default." - option: "include: [DIR, FILE, ...]" -- name: Keep files - description: "When clobbering the site destination, keep the selected files. Useful for files that are not generated by jekyll; e.g. files or assets that are generated by your build tool. The paths are relative to the destination." - option: "keep_files: [DIR, FILE, ...]" -- name: Time Zone - description: "Set the time zone for site generation. This sets the TZ environment variable, which Ruby uses to handle time and date creation and manipulation. Any entry from the IANA Time Zone Database is valid, e.g. America/New_York. A list of all available values can be found here. When serving on a local machine, the default time zone is set by your operating system. But when served on a remote host/server, the default time zone depends on the server's setting or location." - option: "timezone: TIMEZONE" -- name: Encoding - description: "Set the encoding of files by name (only available for Ruby 1.9 or later). The default value is utf-8 starting in 2.0.0, and nil before 2.0.0, which will yield the Ruby default of ASCII-8BIT. Available encodings can be shown by the command ruby -e 'puts Encoding::list.join(\"\\n\")'." - option: "encoding: ENCODING" -build: -- name: Regeneration - description: Enable auto-regeneration of the site when files are modified. - flag: -w, --[no-]watch -- name: Configuration - description: >- - Specify config files instead of using _config.yml automatically. - Settings in later files override settings in earlier files. - flag: --config FILE1[,FILE2,...] -- name: Plugins - description: >- - Specify plugin directories instead of using _plugins/ automatically. - option: "plugins_dir: [ DIR1,... ]" - flag: -p, --plugins DIR1[,DIR2,...] -- name: Layouts - description: >- - Specify layout directory instead of using _layouts/ automatically. - option: "layout_dir: DIR" - flag: --layouts DIR -- name: Drafts - description: Process and render draft posts. - option: "show_drafts: BOOL" - flag: -D, --drafts -- name: Environment - description: Use a specific environment value in the build. - flag: JEKYLL_ENV=production -- name: Future - description: Publish posts or collection documents with a future date. - option: "future: BOOL" - flag: --future -- name: Unpublished - description: Render posts that were marked as unpublished. - option: "unpublished: BOOL" - flag: --unpublished -- name: LSI - description: >- - Produce an index for related posts. Requires the - classifier-reborn plugin. - option: "lsi: BOOL" - flag: --lsi -- name: Limit Posts - description: Limit the number of posts to parse and publish. - option: "limit_posts: NUM" - flag: --limit_posts NUM -- name: Force polling - description: Force watch to use polling. - option: "force_polling: BOOL" - flag: --force_polling -- name: Verbose output - description: Print verbose output. - flag: -V, --verbose -- name: Silence Output - description: Silence the normal output from Jekyll during a build. - flag: -q, --quiet -- name: Incremental build - description: >- - Enable the experimental incremental build feature. Incremental build only - re-builds posts and pages that have changed, resulting in significant performance - improvements for large sites, but may also break site generation in certain - cases. - option: "incremental: BOOL" - flag: -I, --incremental -- name: Liquid profiler - description: Generate a Liquid rendering profile to help you identify performance bottlenecks. - option: "profile: BOOL" - flag: --profile -- name: Strict Front Matter - description: Cause a build to fail if there is a YAML syntax error in a page's front matter. - option: "strict_front_matter: BOOL" - flag: --strict_front_matter -- name: Base URL - description: Serve the website from the given base URL. - option: "baseurl: URL" - flag: -b, --baseurl URL -- name: Trace - description: Show the full backtrace when an error occurs. - flag: -t, --trace -serve: -- name: Local Server Port - description: Listen on the given port. - option: - - "port: PORT" - flag: - - -P, --port PORT -- name: Local Server Hostname - description: Listen at the given hostname. - option: - - "host: HOSTNAME" - flag: - - -H, --host HOSTNAME -- name: Live Reload - description: Reload a page automatically on the browser when its content is edited. - option: - - "livereload: BOOL" - flag: - - -l, --livereload -- name: Live Reload Ignore - description: File glob patterns for LiveReload to ignore. - option: - - "livereload_ignore: [ GLOB1,... ]" - flag: - - --livereload-ignore GLOB1[,GLOB2,...] -- name: Live Reload Min/Max Delay - description: Minimum/Maximum delay before automatically reloading page. - option: - - "livereload_min_delay: SECONDS" - - "livereload_max_delay: SECONDS" - flag: - - --livereload-min-delay SECONDS - - --livereload-max-delay SECONDS -- name: Live Reload Port - description: Port for LiveReload to listen on. - flag: - - --livereload-port PORT -- name: Open URL - description: Open the site's URL in the browser. - option: - - "open_url: BOOL" - flag: - - -o, --open-url -- name: Detach - description: Detach the server from the terminal. - option: - - "detach: BOOL" - flag: - - -B, --detach -- name: Skips the initial site build - description: Skips the initial site build which occurs before the server is started. - option: - - "skip_initial_build: BOOL" - flag: - - --skip-initial-build -- name: Show Directory Listing - description: Show a directory listing instead of loading your index file. - option: - - "show_dir_listing: BOOL" - flag: - - --show-dir-listing -- name: X.509 (SSL) Private Key - description: SSL Private Key, stored or symlinked in the site source. - flag: - - --ssl-key -- name: X.509 (SSL) Certificate - description: SSL Public certificate, stored or symlinked in the site source. - flag: - - --ssl-cert diff --git a/docs/_data/config_options/build.yml b/docs/_data/config_options/build.yml new file mode 100644 index 00000000..c4d5606d --- /dev/null +++ b/docs/_data/config_options/build.yml @@ -0,0 +1,110 @@ +- name: Regeneration + description: Enable auto-regeneration of the site when files are modified. + flag: "-w, --[no-]watch" + + +- name: Configuration + description: >- + Specify config files instead of using _config.yml automatically. + Settings in later files override settings in earlier files. + flag: "--config FILE1[,FILE2,...]" + + +- name: Plugins + description: >- + Specify plugin directories instead of using _plugins/ automatically. + option: "plugins_dir: [ DIR1,... ]" + flag: "-p, --plugins DIR1[,DIR2,...]" + + +- name: Layouts + description: >- + Specify layout directory instead of using _layouts/ automatically. + option: "layout_dir: DIR" + flag: --layouts DIR + + +- name: Drafts + description: Process and render draft posts. + option: "show_drafts: BOOL" + flag: -D, --drafts + + +- name: Environment + description: Use a specific environment value in the build. + flag: JEKYLL_ENV=production + + +- name: Future + description: Publish posts or collection documents with a future date. + option: "future: BOOL" + flag: --future + + +- name: Unpublished + description: Render posts that were marked as unpublished. + option: "unpublished: BOOL" + flag: --unpublished + + +- name: LSI + description: >- + Produce an index for related posts. Requires the + classifier-reborn plugin. + option: "lsi: BOOL" + flag: --lsi + + +- name: Limit Posts + description: Limit the number of posts to parse and publish. + option: "limit_posts: NUM" + flag: --limit_posts NUM + + +- name: Force polling + description: Force watch to use polling. + option: "force_polling: BOOL" + flag: --force_polling + + +- name: Verbose output + description: Print verbose output. + flag: -V, --verbose + + +- name: Silence Output + description: Silence the normal output from Jekyll during a build. + flag: -q, --quiet + + +- name: Incremental build + description: >- + Enable the experimental incremental build feature. Incremental build only + re-builds posts and pages that have changed, resulting in significant performance + improvements for large sites, but may also break site generation in certain + cases. + option: "incremental: BOOL" + flag: -I, --incremental + + +- name: Liquid profiler + description: Generate a Liquid rendering profile to help you identify performance bottlenecks. + option: "profile: BOOL" + flag: --profile + + +- name: Strict Front Matter + description: Cause a build to fail if there is a YAML syntax error in a page's front matter. + option: "strict_front_matter: BOOL" + flag: --strict_front_matter + + +- name: Base URL + description: Serve the website from the given base URL. + option: "baseurl: URL" + flag: -b, --baseurl URL + + +- name: Trace + description: Show the full backtrace when an error occurs. + flag: -t, --trace diff --git a/docs/_data/config_options/global.yml b/docs/_data/config_options/global.yml new file mode 100644 index 00000000..7f7feb3c --- /dev/null +++ b/docs/_data/config_options/global.yml @@ -0,0 +1,77 @@ +- name: Site Source + description: Change the directory where Jekyll will read files + option: "source: DIR" + flag: -s, --source DIR + + +- name: Site Destination + description: Change the directory where Jekyll will write files + option: "destination: DIR" + flag: -d, --destination DIR + + +- name: Safe + description: >- + Disable non-whitelisted plugins, caching to disk, and ignore symbolic links. + option: "safe: BOOL" + flag: --safe + + +- name: Disable Disk Cache + version-badge: 4.1.0 + description: >- + Disable caching of content to disk in order to skip creating a .jekyll-cache or similar directory at + the source to avoid interference with virtual environments and third-party directory watchers. Caching to disk is + always disabled in safe mode. + option: "disable_disk_cache: BOOL" + flag: --disable-disk-cache + + +- name: Ignore theme configuration + version-badge: 4.1.0 + description: >- + Jekyll 4.0 started allowing themes to bundle a _config.yml to simplify theme-onboarding for new users. + In the unfortunate situation that importing a bundled theme configuration messes up the merged site-configuration, + the user can configure Jekyll to not import the theme-config entirely. + option: "ignore_theme_config: BOOL" + + +- name: Exclude + description: >- + Exclude directories and/or files from the conversion. These exclusions are relative to the site's source directory + and cannot be outside the source directory. + option: "exclude: [DIR, FILE, ...]" + + +- name: Include + description: >- + Force inclusion of directories and/or files in the conversion. .htaccess is a good example since + dotfiles are excluded by default. + option: "include: [DIR, FILE, ...]" + + +- name: Keep files + description: >- + When clobbering the site destination, keep the selected files. Useful for files that are not generated by jekyll; + e.g. files or assets that are generated by your build tool. The paths are relative to the destination. + option: "keep_files: [DIR, FILE, ...]" + + +- name: Time Zone + description: >- + Set the time zone for site generation. This sets the TZ environment variable, which Ruby uses to handle + time and date creation and manipulation. Any entry from the + IANA Time Zone Database + is valid, e.g. America/New_York. A list of all available values can be found + here. + When serving on a local machine, the default time zone is set by your operating system. But when served on a remote + host/server, the default time zone depends on the server's setting or location. + option: "timezone: TIMEZONE" + + +- name: Encoding + description: >- + Set the encoding of files by name (only available for Ruby 1.9 or later). The default value is utf-8 + starting in 2.0.0, and nil before 2.0.0, which will yield the Ruby default of ASCII-8BIT. + Available encodings can be shown by the command ruby -e 'puts Encoding::list.join("\n")'. + option: "encoding: ENCODING" diff --git a/docs/_data/config_options/serve.yml b/docs/_data/config_options/serve.yml new file mode 100644 index 00000000..13fc70b2 --- /dev/null +++ b/docs/_data/config_options/serve.yml @@ -0,0 +1,71 @@ +- name: Local Server Port + description: Listen on the given port. + option: "port: PORT" + flag: "-P, --port PORT" + + +- name: Local Server Hostname + description: Listen at the given hostname. + option: "host: HOSTNAME" + flag: "-H, --host HOSTNAME" + + +- name: Live Reload + description: Reload a page automatically on the browser when its content is edited. + option: "livereload: BOOL" + flag: "-l, --livereload" + + +- name: Live Reload Ignore + description: File glob patterns for LiveReload to ignore. + option: "livereload_ignore: [ GLOB1,... ]" + flag: "--livereload-ignore GLOB1[,GLOB2,...]" + + +- name: Live Reload Min/Max Delay + description: Minimum/Maximum delay before automatically reloading page. + options: + - "livereload_min_delay: SECONDS" + - "livereload_max_delay: SECONDS" + flags: + - "--livereload-min-delay SECONDS" + - "--livereload-max-delay SECONDS" + + +- name: Live Reload Port + description: Port for LiveReload to listen on. + flag: "--livereload-port PORT" + + +- name: Open URL + description: Open the site's URL in the browser. + option: "open_url: BOOL" + flag: "-o, --open-url" + + +- name: Detach + description: Detach the server from the terminal. + option: "detach: BOOL" + flag: "-B, --detach" + + +- name: Skips the initial site build + description: Skips the initial site build which occurs before the server is started. + option: "skip_initial_build: BOOL" + flag: "--skip-initial-build" + + +- name: Show Directory Listing + description: Show a directory listing instead of loading your index file. + option: "show_dir_listing: BOOL" + flag: "--show-dir-listing" + + +- name: X.509 (SSL) Private Key + description: "SSL Private Key, stored or symlinked in the site source." + flag: "--ssl-key" + + +- name: X.509 (SSL) Certificate + description: "SSL Public certificate, stored or symlinked in the site source." + flag: "--ssl-cert" diff --git a/docs/_docs/configuration/options.md b/docs/_docs/configuration/options.md index 4206c221..7713f0cc 100644 --- a/docs/_docs/configuration/options.md +++ b/docs/_docs/configuration/options.md @@ -92,12 +92,8 @@ class="flag">flags (specified on the command-line) that control them.

{{ setting.description }}

- {% if setting.option %} -

{{ setting.option }}

- {% endif %} - {% if setting.flag %} -

{{ setting.flag }}

- {% endif %} + {% if setting.option %}

{{ setting.option }}

{% endif %} + {% if setting.flag %}

{{ setting.flag }}

{% endif %} {% endfor %} @@ -133,15 +129,19 @@ before your site is served. {% if setting.option %} +

{{ setting.option }}

+ {% elsif setting.options %}

- {% for option in setting.option %} + {% for option in setting.options %} {{ option }}
{% endfor %}

{% endif %} {% if setting.flag %} +

{{ setting.flag }}

+ {% elsif setting.flags %}

- {% for flag in setting.flag %} + {% for flag in setting.flags %} {{ flag }}
{% endfor %}