Resolving Path References

Default Path References

When Styleguide builds a custom theme, it includes the resources in the default theme, which can be overridden or extended by the custom theme. Styleguide looks up files that are referenced by other data or template files, which can be specified with absolute or relative paths. To find a referenced file, Styleguide first looks in the custom theme directory, then in the default theme directory.

Example: Absolute Path

The ArticleBreakingNews.json file is theme-specific, residing in the /themes/brightspot-theme-canvas/styleguide/article directory. The _include key in the file is set to /article/ArticlePage.json.

The Styleguide lookup logic is as follows:

  1. In the theme-specific directory, look for /themes/brightspot-theme-canvas/styleguide/article/ArticlePage.json.
  2. If /article/ArticlePage.json is not found in the theme-specific directory, look in the default theme directory: /styleguide/article.
  3. Throw exception if file not found.

Example: Relative Path

The EmployeePage.json file is theme-specific, residing in the /themes/brightspot-theme-canvas/styleguide/corporate/employee directory. The _include key in the file is set to ../../core/page/ContentPage.hbs.

The Styleguide lookup logic is as follows:

  1. In the theme-specific directory, look for /themes/brightspot-theme-canvas/styleguide/core/page/ContentPage.hbs.
  2. If /core/page/ContentPage.hbs is not found in the theme-specific directory, look in the default theme directory: /styleguide/core/page.
  3. Throw exception if file not found.

Extended Path References

The section Default Path References states that by default, Styleguide looks for files within the current theme’s directory or within the default theme’s directory. You can extend or limit path references using the sources key in the theme’s configuration file _config.json.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
{
   "sources": [
       {
         "source": "/path/to/templates1",
         "hidden": false
       },
       {
         "source": "/path/to/templates2",
         "hidden": true
       }
   ]
 }

In the previous snippet—

  • Lines 4 and 8 indicate Styleguide includes templates found in the directories /path/to/templates1/ and /path/to/templates2/.
  • Line 5 indicates that templates found in /path/to/templates1/ appear in the Styleguide UI. Omitting the key hidden is the same as "hidden": false.
  • Line 9 indicates that templates found in /path/to/templates2/ do not appear in the Styleguide UI (but they are included in override and extend inheritance evaluations).

See also: