Document child themes

Comment untested works

cms-components.md

@@ -1,14 +1,14 @@
 # Using Components
 
 - [Introduction](#introduction)
-- [Component aliases](#aliases)
-- [Using external property values](#external-property-values)
-- [Passing variables to components](#component-variables)
-- [Customizing default markup](#customizing-default-markup)
-    - [Moving default markup to a partial](#moving-default-markup)
-    - [Overriding component partials](#overriding-partials)
-- [The "View Bag" component](#viewbag-component)
-- [Soft components](#soft-components)
+- [Component Aliases](#aliases)
+- [Using External Property Values](#external-property-values)
+- [Passing Variables to Components](#component-variables)
+- [Customizing Default Markup](#customizing-default-markup)
+    - [Moving Default Markup to a Partial](#moving-default-markup)
+    - [Overriding Component Partials](#overriding-partials)
+- [The "View Bag" Component](#viewbag-component)
+<!-- - [Soft Components](#soft-components) -->
 
 Components are configurable building elements that can be attached to any page, partial or layout. Components are key features of October. Each component implements some functionality that extends your website. Components can output HTML markup on a page, but it is not necessary - other important features of components are handling [AJAX requests](../ajax/introduction), handling form postbacks and handling the page execution cycle, that allows to inject variables to pages or implement the website security.
 
@@ -38,7 +38,7 @@ When you refer a component, it automatically creates a page variable that matche
 > **Note:** If two components with the same name are assigned to a page and layout together, the page component overrides any properties of the layout component.
 
 <a name="aliases"></a>
-## Components aliases
+## Components Aliases
 
 If there are two plugins that register components with the same name, you can attach a component by using its fully qualified class name and assigning it an *alias*:
 
@@ -57,7 +57,7 @@ The aliases also allow you to define multiple components of the same class on a
     maxItems = 20
 
 <a name="external-property-values"></a>
-## Using external property values
+## Using External Property Values
 
 By default property values are initialized in the Configuration section where the component is defined, and the property values are static, like this:
 
@@ -76,7 +76,7 @@ However there is a way to initialize properties with values loaded from external
 Assuming that in the example above the component **demoTodo** is defined in a partial, it will be initialized with a value loaded from the **maxItems** partial variable:
 
     {% partial 'my-todo-partial' maxItems='10' %}
-    
+
 You may use dot notation to retrieve a deeply nested value from an external parameter:
 
     [demoTodo]
@@ -98,7 +98,7 @@ The page, the component belongs to, should have a corresponding [URL parameter](
 In the October back-end you can use the Inspector tool for assigning external values to component properties. In the Inspector you don't need to use the curly brackets to enter the parameter name. Each field in the Inspector has an icon on the right side, which opens the external parameter name editor. Enter the parameter name as `paramName` for partial variables or `:paramName` for URL parameters.
 
 <a name="component-variables"></a>
-## Passing variables to components
+## Passing Variables to Components
 
 Components can be designed to use variables at the time they are rendered, similar to [Partial variables](partials#partial-variables), they can be specified after the component name in the `{% component %}` tag. The specified variables will explicitly override the value of the [component properties](../plugin/components#component-properties), including [external property values](#external-property-values).
 
@@ -109,12 +109,12 @@ In this example, the **maxItems** property of the component will be set to *7* a
 > **Note**: Not all components support passing variables when rendering.
 
 <a name="customizing-default-markup"></a>
-## Customizing default markup
+## Customizing Default Markup
 
 The markup provided by components is generally intended as a usage example for the Component. In some cases you may wish to modify the appearance and output of a component. [Moving the default markup to a theme partial](#moving-default-markup) is suitable to completely overhaul a component. [Overriding the component partials](#overriding-partials) is useful for cherry picking areas to customize.
 
 <a name="moving-default-markup"></a>
-### Moving default markup to a partial
+### Moving Default Markup to a Partial
 
 Each component can have an entry point partial called **default.htm** that is rendered when the `{% component %}` tag is called, in the following example we will assume the component is called **blogPost**.
 
@@ -141,7 +141,7 @@ This is the only change needed to allow the default component markup to work any
 This process can be repeated for all other partials found in the component partial directory.
 
 <a name="overriding-partials"></a>
-### Overriding component partials
+### Overriding Component Partials
 
 All component partials can be overridden using the theme partials. If a component called **channel** uses the **title.htm** partial.
 
@@ -170,7 +170,7 @@ The partial subdirectory name can be customized to anything by simply assigning
 Now we can override the **title.htm** partial by creating a file in our theme called **partials/foobar/title.htm**.
 
 <a name="viewbag-component"></a>
-## The "View Bag" component
+## The "View Bag" Component
 
 There is a special component included in October called `viewBag` that can be used on any page or layout. It allows ad hoc properties to be defined and accessed inside the markup area easily as variables. A good usage example is defining an active menu item inside a page:
 
@@ -198,8 +198,9 @@ Any property defined for the component is then made available inside the page, l
 
 > **Note**: The viewBag component is hidden on the back-end and is only available for file-based editing. It can also be used by other plugins to store data.
 
+<!--
 <a name="soft-components"></a>
-## Soft components
+## Soft Components
 
 Soft components are components in a theme that will continue to operate even if the linked component is no longer available. This allows theme and site developers to specify optional plugin components in their themes that will provide specific functionality if the plugin and/or component is present, while allowing the site to continue to function should the component no longer exist.
 
@@ -233,4 +234,5 @@ As soft components do not contain any of the data that the component may provide
         <div class="channel">
             {% channel.name %}
         </div>
-    {% endif %}
+    {% endif %}
+-->

cms-themes.md

@@ -7,13 +7,14 @@
     - [Configuration Section](#configuration-section)
     - [PHP Code Section](#php-section)
     - [Twig Markup Section](#twig-section)
-- [Theme Logging](#theme-logging)
 - [Database Driven Themes](#database-driven-themes)
+- [Child Themes](#child-themes)
+- [Theme Logging](#theme-logging)
 
 <a name="introduction"></a>
 ## Introduction
 
-Themes define the appearance of your website or web application built with October CMS. October themes are completely file-backed and can be managed with any version control system, for example, Git. This page gives you a high-level description of October themes. You will find more details about [pages](pages), [partials](partials), [layouts](layouts) and [content files](content) in the corresponding articles.
+Themes define the appearance of your website or web application built with October CMS. They are completely file-backed and can be managed with any version control system, for example, Git. This page gives you a high-level description of October themes. You will find more details about [pages](pages), [partials](partials), [layouts](layouts) and [content files](content) in the corresponding articles.
 
 Themes are directories that reside in the **themes** directory by default. Themes can contain the following objects:
 
@@ -51,7 +52,7 @@ Below, you can see an example theme directory structure. Each October theme is r
 <a name="subdirectories"></a>
 ### Subdirectories
 
-October supports single level subdirectories for **pages**, **partials**, **layouts** and **content** files, while the **assets** directory can have any structure. This simplifies the organization of large websites. In the example directory structure below, you can see that the **pages** and **partials** directories contain the **blog** subdirectory, and the **content** directory contains the **home** subdirectory.
+October CMS supports single level subdirectories for **pages**, **partials**, **layouts** and **content** files, while the **assets** directory can have any structure. This simplifies the organization of large websites. In the example directory structure below, you can see that the **pages** and **partials** directories contain the **blog** subdirectory, and the **content** directory contains the **home** subdirectory.
 
     themes/
       website/
@@ -158,28 +159,37 @@ As a general way of setting variables, you should use the array access method on
 <a name="twig-section"></a>
 ### Twig Markup Section
 
-The Twig section defines the markup to be rendered by the template. In the Twig section, you can use functions, tags, and filters [provided by October](../markup), all the [native Twig features](http://twig.sensiolabs.org/documentation), or those [provided by plugins](../plugin/registration#extending-twig). The content of the Twig section depends on the template type (page, layout, or partial). You can find more information about specific Twig objects further in the documentation.
+The Twig section defines the markup to be rendered by the template. In the Twig section, you can use functions, tags, and filters [provided by October CMS](../markup), all the [native Twig features](http://twig.sensiolabs.org/documentation), or those [provided by plugins](../plugin/registration#extending-twig). The content of the Twig section depends on the template type (page, layout, or partial). You can find more information about specific Twig objects further in the documentation.
 
 More information can be found [in the Markup guide](../markup).
 
-<a name="theme-logging"></a>
-## Theme Logging
+<a name="database-driven-themes"></a>
+## Database Driven Themes
 
-October CMS has the ability to record every change made to a theme, called ThemeL Logging and is disabled by default.
+In some cases you may not have access to write to the filesystem to make changes to the theme. Database driven themes allows you to store all changes to CMS templates in the database.
 
-Since layouts and pages store most of the data in flat files, it's possible for you or your clients to accidentally lose content. For example, switching the layout of a page will modify the scaffold of the page, and, as such, will result in data loss.
+To enable this feature for a single theme, navigate to **Settings > Frontend Theme**, select **Edit Properties** and check the checkbox called **Save Changes in Database**.
 
-To enable Theme Logging, simply go to **Settings > Log Settings** and enable **Log Theme Changes**. All changes are now logged.
+Alternatively you can enable this feature globally for all themes with the config item `cms.database_templates` or using the environment variable.
 
-The theme change log can be viewed at **Settings > Theme log**. Each change has an overview of what has been added/removed, along with a copy of the changed file before and after. You can use this information to decide the appropriate action, to aid the reversion of these changes, if necessary.
+    CMS_DB_TEMPLATES=true
 
-<a name="database-driven-themes"></a>
-## Database Driven Themes
+> **Note**: Assets files like images and stylesheets do not save in the database and cannot be modified without access to the filesystem.
+
+<a name="child-themes"></a>
+## Child Themes
+
+Child themes allow for the possibility of theme inheritence. A good use of this is when you have a third party theme or a theme that is in read-only mode. A child theme will reference a parent and use it as a fallback source.
+
+If a page named `home.htm` exists in the parent theme but not the child, it treats it the same as if it did; the URL is active, and you can open the page like normal. When saving the page in the backend area, a new file is created in the child theme to override the contents.
 
-October CMS comes with another very useful feature, disabled by default, called Database Driven Themes. When this feature is enabled (by setting `cms.databaseTemplates` to `true`, or `null` when `app.debug` is `false`); the database layer stores all modified CMS files in the database. Files that are not modified continue to be loaded from the filesystem. There is a [`theme:sync $themeDir`](../console/commands#theme-sync-command) console command that can be used to sync changes between the filesystem and database.
+To enable this feature for a theme, navigate to **Settings > Frontend Theme**, select **Edit Properties** and select a parent from the **Parent Theme** dropdown list.
+
+<a name="theme-logging"></a>
+## Theme Logging
 
-Files modified in the database are cached to indicate that they should be loaded from the database.
+Since layouts and pages store most of the data in flat files, you or your clients can lose content accidentally. For example, switching the layout of a page will modify the scaffold of the page and, as such, will result in data loss.
 
->**NOTE:** Themes can store templates in the database if `cms.databaseTemplates` is enabled, see the [database driven themes](#database-driven-themes) section for more information.
+October CMS can record every change made to a theme called Theme Logging, and this feature is disabled by default. To enable Theme Logging, go to **Settings > Log Settings** and enable **Log Theme Changes**.
 
->**NOTE:** All CMS template objects (ex. `Layout`, `Page`, `Content`, `Partial`, `Meta`, etc) are stored in the database when this feature is enabled and a change is made to the template in question; however theme asset files will **not** be.
+You may now view the theme changelog via **Settings > Theme Log** where you can observe an overview of each change. You can use this information to decide the appropriate action to aid the regression of these changes, if necessary.

config/toc-docs.yaml

@@ -87,7 +87,7 @@ Services:
     services/error-log: "Errors & Logging"
     services/events: "Events"
     services/html: "Forms & Html"
-    services/image-resizing: "Image Resizing"
+    # services/image-resizing: "Image Resizing"
     services/filesystem-cdn: "Filesystem / CDN"
     services/hashing-encryption: "Hashing & Encryption"
     services/helpers: "Helpers"

config/toc-markup.yaml

@@ -36,16 +36,16 @@ Filters:
   icon: "icon-quote-right"
   itemClass: "code-item"
   pages:
-    markup/filter-app: "| app"
-    markup/filter-page: "| page"
-    markup/filter-theme: "| theme"
-    markup/filter-media: "| media"
-    markup/filter-resize: "| resize"
-    markup/filter-image-width: "| imageWidth"
-    markup/filter-image-height: "| imageHeight"
-    markup/filter-md: "| md"
-    markup/filter-raw: "| raw"
-    markup/filter-default: "| default"
+    markup/filter-app: "|app"
+    markup/filter-page: "|page"
+    markup/filter-theme: "|theme"
+    markup/filter-media: "|media"
+    # markup/filter-resize: "| resize"
+    # markup/filter-image-width: "| imageWidth"
+    # markup/filter-image-height: "| imageHeight"
+    markup/filter-md: "|md"
+    markup/filter-raw: "|raw"
+    markup/filter-default: "|default"
 
 Functions:
   icon: "icon-eraser"