Merge pull request #5573 from ashmaroli/directory-docs

Merge pull request 5573

docs/_docs/structure.md

@@ -17,6 +17,8 @@ A basic Jekyll site usually looks something like this:
 ```sh
 .
 ├── _config.yml
+├── _data
+|   └── members.yml
 ├── _drafts
 |   ├── begin-with-the-crazy-ideas.md
 |   └── on-simplicity-in-technology.md
@@ -29,13 +31,25 @@ A basic Jekyll site usually looks something like this:
 ├── _posts
 |   ├── 2007-10-29-why-every-programmer-should-play-nethack.md
 |   └── 2009-04-26-barcamp-boston-4-roundup.md
-├── _data
+├── _sass
-|   └── members.yml
+|   ├── _base.scss
+|   └── _layout.scss
 ├── _site
 ├── .jekyll-metadata
-└── index.html
+└── index.html # can also be an 'index.md' with valid YAML Frontmatter
 ```
 
+<div class="note info">
+  <h5>Directory structure of Jekyll sites using gem-based themes</h5>
+  <p>
+    Starting <strong>Jekyll 3.2</strong>, a new Jekyll project bootstrapped with <code>jekyll new</code> uses <a href="../themes/">gem-based themes</a> to define the look of the site. This results in a lighter default directory structure : <code>_layouts</code>, <code>_includes</code> and <code>_sass</code> are stored in the theme-gem, by default.
+  </p>
+  <br />
+  <p>
+     <a href="https://github.com/jekyll/minima">minima</a> is the current default theme, and <code>bundle show minima</code> will show you where minima theme's files are stored on your computer.
+  </p>
+</div>
+
 An overview of what each of these does:
 
 <div class="mobile-side-scroller">
@@ -53,11 +67,9 @@ An overview of what each of these does:
       </td>
       <td>
         <p>
-
           Stores <a href="../configuration/">configuration</a> data. Many of
           these options can be specified from the command line executable but
           it’s easier to specify them here so you don’t have to remember them.
-
         </p>
       </td>
     </tr>
@@ -67,11 +79,9 @@ An overview of what each of these does:
       </td>
       <td>
         <p>
-
           Drafts are unpublished posts. The format of these files is without a
           date: <code>title.MARKUP</code>. Learn how to <a href="../drafts/">
           work with drafts</a>.
-
         </p>
       </td>
     </tr>
@@ -81,13 +91,11 @@ An overview of what each of these does:
       </td>
       <td>
         <p>
-
           These are the partials that can be mixed and matched by your layouts
           and posts to facilitate reuse. The liquid tag
           <code>{% raw %}{% include file.ext %}{% endraw %}</code>
           can be used to include the partial in
           <code>_includes/file.ext</code>.
-
         </p>
       </td>
     </tr>
@@ -97,14 +105,12 @@ An overview of what each of these does:
       </td>
       <td>
         <p>
-
           These are the templates that wrap posts. Layouts are chosen on a
           post-by-post basis in the
           <a href="../frontmatter/">YAML Front Matter</a>,
           which is described in the next section. The liquid tag
           <code>{% raw %}{{ content }}{% endraw %}</code>
           is used to inject content into the web page.
-
         </p>
       </td>
     </tr>
@@ -114,14 +120,12 @@ An overview of what each of these does:
       </td>
       <td>
         <p>
-
           Your dynamic content, so to speak. The naming convention of these
           files is important, and must follow the format:
           <code>YEAR-MONTH-DAY-title.MARKUP</code>.
           The <a href="../permalinks/">permalinks</a> can be customized for
           each post, but the date and markup language are determined solely by
           the file name.
-
         </p>
       </td>
     </tr>
@@ -131,15 +135,25 @@ An overview of what each of these does:
       </td>
       <td>
         <p>
-
           Well-formatted site data should be placed here. The Jekyll engine
-          will autoload all YAML files in this directory (using either the
+          will autoload all data files (using either the <code>.yml</code>,
-          <code>.yml</code>, <code>.yaml</code>, <code>.json</code> or
+          <code>.yaml</code>, <code>.json</code> or <code>.csv</code>
-          <code>.csv</code> formats and extensions) and they will be
+          formats and extensions) in this directory, and they will be
           accessible via `site.data`. If there's a file
           <code>members.yml</code> under the directory, then you can access
           contents of the file through <code>site.data.members</code>.
-
+        </p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p><code>_sass</code></p>
+      </td>
+      <td>
+        <p>
+          These are sass partials that can be imported into your <code>main.scss</code>
+          which will then be processed into a single stylesheet
+          <code>main.css</code> that defines the styles to be used by your site.
         </p>
       </td>
     </tr>
@@ -149,11 +163,9 @@ An overview of what each of these does:
       </td>
       <td>
         <p>
-
           This is where the generated site will be placed (by default) once
           Jekyll is done transforming it. It’s probably a good idea to add this
           to your <code>.gitignore</code> file.
-
         </p>
       </td>
     </tr>
@@ -163,29 +175,26 @@ An overview of what each of these does:
       </td>
       <td>
         <p>
-
           This helps Jekyll keep track of which files have not been modified
           since the site was last built, and which files will need to be
           regenerated on the next build. This file will not be included in the
           generated site. It’s probably a good idea to add this to your
           <code>.gitignore</code> file.
-
         </p>
       </td>
     </tr>
     <tr>
       <td>
-        <p><code>index.html</code> and other HTML, Markdown, Textile files</p>
+        <p><code>index.html</code> or <code>index.md</code> and other HTML,
+        Markdown, Textile files</p>
       </td>
       <td>
         <p>
-
           Provided that the file has a <a href="../frontmatter/">YAML Front
           Matter</a> section, it will be transformed by Jekyll. The same will
           happen for any <code>.html</code>, <code>.markdown</code>,
           <code>.md</code>, or <code>.textile</code> file in your site’s root
           directory or directories not listed above.
-
         </p>
       </td>
     </tr>
@@ -195,14 +204,12 @@ An overview of what each of these does:
       </td>
       <td>
         <p>
-
           Every other directory and file except for those listed above—such as
           <code>css</code> and <code>images</code> folders,
           <code>favicon.ico</code> files, and so forth—will be copied verbatim
           to the generated site. There are plenty of <a href="../sites/">sites
           already using Jekyll</a> if you’re curious to see how they’re laid
           out.
-
         </p>
       </td>
     </tr>