Merge pull request #1 from DocOps/reorg-dirs

1. Renamed `build/` => `_build/`.
2. Renamed `_data/` => `data/`.
3. Renamed `src/` => `content/`.
4. Renamed `content/portal/` => `content/pages/`
5. Converted `_build/includes/built/filename.adoc` to `_build/includes/_built_filename.adoc`.
6. Enhanced README instructions for clarity.
7. Added The MIT License.

The convention I have in mind is root-level directories that start with `_` are _not_ migrated into the build directory during processing. That is, they do not contain what we consider content but rather files that configure or shape the build/output. Small-data files that go in `data/` contain content about the product or other subject matter of the publication. Meanwhile `_templates` contains content that will be expressed more appropriately in preprocessed files, so we can keep that stuff out of `_build/`. The `data/` dir is likely to get moved into `_build/site` or wherever the SSG will look for menu and other data.

Changing `portal/` to `pages/` in the `content/` dir just seems like a good practice. "Page" is a general concept, generally akin to a web page or a section of a book chapter, but for non-topical content. This is a place for miscellaneous web pages you want to accompany your core docs. These may or may not be included in a PDF edition of the same docs.

Flattening the `built/` subdirectory was mainly to eliminate messes caused with relative paths in AsciiDoc. We almost certainly still need to address subdirectories inside `topics/` and `pages/`.

Author: briandominick

LICENSE

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+
+Copyright (c) 2018 Brian Dominick and Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

README.adoc

@@ -8,21 +8,19 @@ This creates a truly open, highly portable system for developing and maintaining
 
 Complete documentation for LDCMF is still being developed.
 
-The following procedure is a *bootstrapping operation* to get an _actual LDCMF project_ started.
+The following procedure is a *bootstrapping operation* to get an _actual LDCMF-based project_ started.
 It further sets up initial files based on custom preferences.
-The newly generated `README.adoc` instructs future users to set up and use your docs.
-
-=== Quickstart
 
 [WARNING]
 This file (`README.adoc`) is the README for the generic LiquiDoc CMF project bootstrap repository.
-If you wish to keep this file, move/rename it _before_ running the quickstart, which generates a proper `README.adoc` for your actual docs project/directory, which this directory and its contents then becomes.
+If you wish to keep this file, move/rename it _before_ running the quickstart, which generates a proper `README.adoc` for your actual docs project/directory, which this directory and its contents then _becomes_.
 
 If you have link:https://git-scm.com/book/en/v2/Getting-Started-Installing-Git[Git] and link:https://www.ruby-lang.org/en/downloads/[Ruby runtime] installed, you can get going with LiquiDoc CMF in a few quick steps.
 
 . Clone this repo.
 +
 [subs="quotes"]
+.Example
 ----
 git clone git@github.com:DocOps/liquidoc-cmf.git *docs_dir*
 ----
@@ -38,51 +36,57 @@ cd docs_dir
 
 . Re-associate your files with the proper repository.
 
-.. _If this project is its own Git repo_, change the project's remote origin Git repository.
+.. _If your docs project is its own Git repo_, change the project's remote origin Git repository.
 +
 ----
 git remote set-url origin git://github.com:your-project/your-repo-name.git
 ----
 +
 Replace this URI with your own.
 
-.. _If this project is part of a parent directory's Git repo_, remove local Git files.
+.. _If your docs project is part of a parent directory's Git repo_, remove local Git files so your new docs source will be absorbed into the parent repo.
 +
 ----
 rm -rf .git
 ----
++
+Now your new directory/files will appear as uncommitted additions to the parent project (`git status`).
 
 . Run Bundler to install dependencies.
 +
 ----
-bundle install
+bundle
 ----
 +
-If Bundler is not installed, run `gem install bundler`, then repeat this command.
+If an error indicates Bundler is not installed, run `gem install bundler`, then repeat this command.
 
 . Rename this README so _init_ does not overwrite it.
 +
 .Example
 ----
 mv README.adoc README.meta.adoc
 ----
++
+This file may confuse future users; we advise removing it before sharing your LDCMF project.
 
 . Edit your project metafile.
 +
-In your favorite text/code editor, open `_data/meta.yml` and fill out the required info, then *save the file*.
+In your favorite text/code editor, open `data/meta.yml` and fill out the required info, then *save the file*.
 
 . Run LiquiDoc with the LDCMF initialization config.
 +
 ----
 bundle exec liquidoc -c _init/init.yml
 ----
++
+This procedure customizes a few starter files based on `meta.yml`.
 
-. You can now review and edit your `README.adoc` and `src/index.adoc` files with custom content.
+. You can now review your `README.adoc` and `content/index.adoc` files, editing and populating them with custom content.
 
 . Delete or move the `README.meta.adoc` file (this file) and the `_init/` directory, which you will no longer need.
 
 Further instructions are in your new README!
-The new README file is oriented for your project's future users, so you don't need to repeat setup steps.
+The new README file is oriented for your project's future users (and you!), so you don't need to repeat setup steps.
 Just run your first build.
 
 == Structure
@@ -95,15 +99,15 @@ liquidoc-cmf/
 ├── _configs/
 │   ├── asciidoctor.yml
 │   └── build-docs.yml
-├── _data/
+├── data/
 │   └── meta.yml
 ├── _templates/
 │   └── liquid/
 │       └── company.asciidoc
-├── src/
+├── content/
 │   ├── assets/
 │   ├── includes/
-│   ├── portal/
+│   ├── pages/
 │   ├── topics/
 │   └── index.adoc
 └── theme/
@@ -112,7 +116,7 @@ Gemfile
 ----
 
 [NOTE]
-Empty directories (ex., `src/assets/`) must be manually added.
+Empty directories (ex., `content/assets/`) must be manually added.
 
 == Contributing
 

_configs/asciidoctor.yml

@@ -1,2 +1,4 @@
 # This file contains global Asciidoctor attributes
 imagesdir: assets/images
+safe: 0
+icons: font

_configs/build-docs.yml

@@ -1,22 +1,22 @@
 # Move critical files to the temporary build directory
 - action: migrate
-  source: src
-  target: build
+  source: content/
+  target: _build/
   options:
-    inclusive: false # Duplicate the files without the src/ dir
+    inclusive: false # Duplicate the files without the content/ dir
 - action: migrate
-  source: theme
-  target: build
+  source: theme/
+  target: build/
 - action: parse
-  data: _data/meta.yml
+  data: data/meta.yml
   builds:
-  - output: build/includes/built/company-info.adoc
+  - output: _build/includes/_built_company-info.adoc
     template: _templates/liquid/company-info.asciidoc
 # Render your publication with Asciidoctor
 - action: render
-  source: build/index.adoc
+  source: _build/index.adoc
   data: _configs/asciidoctor.yml
   builds:
-  - output: build/output/docs.html
+  - output: _build/output/docs.html
     properties:
-      files: _data/meta.yml
+      files: data/meta.yml

_init/init.yml

@@ -1,8 +1,8 @@
 - action: parse
   data:
-    file: _data/meta.yml
+    file: data/meta.yml
   builds:
     - output: README.adoc
       template: _init/templates/init_readme.asciidoc
-    - output: src/index.adoc
+    - output: content/index.adoc
       template: _init/templates/init_index.asciidoc

_init/templates/init_index.asciidoc

@@ -2,4 +2,4 @@
 
 == Maker Info
 
-include::includes/built/company-info.adoc[]
+include::includes/_built_company-info.adoc[]

_init/templates/init_readme.asciidoc

@@ -43,6 +43,6 @@ bundle exec liquidoc -c _configs/build-docs.yml
 
 == Build
 
-To build, run `bundle exec liquidoc -c _config/build-docs.yml`.
+To build, run `bundle exec liquidoc -c _configs/build-docs.yml`.
 
-Check out the results in `build/output/`.
+Check out the results in `_build/output/`.