diff --git a/.gitignore b/.gitignore index 3041038..90c1a55 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,3 @@ build Gemfile.lock +.DS_Store diff --git a/Gemfile b/Gemfile index 4f0c839..cdd0137 100644 --- a/Gemfile +++ b/Gemfile @@ -12,7 +12,7 @@ group :asciidoctor_plugins do gem 'asciidoctor-diagram' end -# gem 'jekyll' -# group :jekyll_plugins do -# gem 'jekyll-asciidoc' -# end +gem 'jekyll' +group :jekyll_plugins do + gem 'jekyll-asciidoc' +end diff --git a/README.adoc b/README.adoc index bd5adc1..e8524bd 100644 --- a/README.adoc +++ b/README.adoc @@ -1,122 +1,359 @@ +// This AsciiDoc file must be rendered to be properly viewed. +// The easiest way to view it rendered is on GitHub at +// https://github.com/DocOps/liquidoc-cmf +// OR copy and paste these contents into +// https://asciidoclive.com +// Everthing BELOW is formatted in AsciiDoc syntax: +// https://asciidoctor.org/docs/what-is-asciidoc/ +// NOTE: +// Some markup in this README is intended to work with +// files that dynamically include portions of this file +// elsewhere in this repository or in other repos. +// In LDCMF, README files are used for core canonical +// information about the codebases/products they serve. = LiquiDoc CMF +:subject_repo: this +// this setting makes this file in line with parent repo +:guide_admin: true +:ldcmf_site_base_url: https://www.ajyl.org +:toc: macro -This repo contains the boilerplate files for, and rudimentary documentation of, a content mamanagement framework (CMF) for combining open-source tools and workflows for documentation management. -LiquiDoc CMF (LDCMF) incorporates two excellent lightweight markup languages (link:http://asciidoctor.org/docs/what-is-asciidoc/[AsciiDoc] and link:https://github.com/darvid/trine/wiki/YAML-Primer[YAML]) with open-source build and publish utilities (link:https://git-scm.com/book/en/v2/Getting-Started-Git-Basics[Git], link:http://asciidoctor.org/[Asciidoctor], link:http://idratherbewriting.com/2015/02/27/static-site-generators-start-to-displace-online-cmss/[static site generators], build and deployment tools, and many others) using a wrapper utility called link:https://github.com/briandominick/liquidoc-gem[*LiquiDoc*]. -This creates a truly open, highly portable system for developing and maintaining docs code the way programmers develop and maintain product code. +This repo contains the bootstrapping files and instructions for a _content management framework_ (CMF) designed for documenting software applications. +Combining open-source tools with collaborative workflows, *LiquiDoc CMF* facilitates writing, editing, coordinating, and deploying technical docs in fully extensible, Git-managed codebases. + +LiquiDoc CMF (*LDCMF*) incorporates two excellent lightweight markup languages (link:http://asciidoctor.org/docs/what-is-asciidoc/[AsciiDoc] and link:https://github.com/darvid/trine/wiki/YAML-Primer[YAML]) with open-source build and publish utilities (link:http://asciidoctor.org/[Asciidoctor], and link:http://idratherbewriting.com/2015/02/27/static-site-generators-start-to-displace-online-cmss/[Jekyll]). +All this is stitched together seamlessly with Liquid templating markup and coordinated by a docs build utility called link:https://github.com/DocOps/liquidoc-gem[*LiquiDoc*]. +This creates a truly open, highly portable and scalable system for developing _docs code_ the way programmers develop _product code_. + +toc::[] + +To learn much more about LiquiDoc CMF and its technology ecosystem (the “AJYL docstack”), link:{ldcmf_site_base_url}/liquidoc-cmf[check out this introduction]. +The remainder of this document assumes you wish to implement the LDCMF _framework_ for a project of your own and instructs the bootstrapping of an appropriate LDCMF environment. == Usage -Complete documentation for LDCMF is still being developed. +[IMPORTANT] +link:{ldcmf_site_base_url}/liquidoc-cmf-guides/admin[*Complete documentation for LDCMF administration is available here.*] -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 following procedure is a *bootstrapping operation* to get an _actual LDCMF-based project_ up and running. +It inflates directories and sets up some initial demonstration files based on preferences you will customize. +link:https://www.ajyl.org/liquidoc-cmf-guides/admin/setup-initialize-docs-env[More thorough setup instructions are available] and highly recommended. [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_. +The file you are reading (`README.adoc`) is the README for the _generic LiquiDoc CMF project_ bootstrap repository. +The procedure it instructs will convert its current generic bootstrap context into your own LDCMF project application. +If you wish to keep this file, move/rename it _before_ running the bootstrapping _init_, since that operation generates a proper `README.adoc` for your _actual docs project_, which this directory and its contents _will then be_. + +If you have link:https://git-scm.com/book/en/v2/Getting-Started-Installing-Git[Git] (for Windows: link:https://git-scm.com/download/win[GitBash] or a Linux emulator like link:http://www.cygwin.com/[Cygwin]) and link:https://www.ruby-lang.org/en/downloads/[Ruby runtime] installed, you can get going with LiquiDoc CMF using this guide. -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. +// tag::bootstrap-steps[] +=== Establish the Environment -. Clone this repo. +. *Navigate to the parent directory* of your new docs directory. ++ +.Example for new project +[source,shell] +---- +cd Documents/workspace +---- ++ +.Example for docs inside a product project +[source,shell] +---- +cd Documents/workspace/my-product +---- + +. *Clone {subject_repo} repo.* + [subs="quotes"] .Example +[source,shell] ---- git clone git@github.com:DocOps/liquidoc-cmf.git *docs_dir* ---- + -Replace `docs_dir` with the directory name you want to give this directory. +Replace `docs_dir` with the directory name you want to give this directory -- either a subdirectory of a parent project or the root directory of a new, independent repo. -. Change to the project directory. +. *Change to the project directory.* + .Example +[source,shell] ---- cd docs_dir ---- -. Re-associate your files with the proper repository. - -.. _If your docs project is its own Git repo_, change the project's remote origin Git repository. +. *Re-associate your files* with the proper repository. +[upperalpha] +.. _If your docs project is its own Git repo_, change the boilerplate project's remote origin Git repository to your own. + +.Example +[source,shell] ---- git remote set-url origin git://github.com:your-project/your-repo-name.git ---- + Replace this URI with your own. -.. _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. +.. _If your docs project is part of a parent directory's Git repo_, remove _local_ Git files (for the LDCMF repo you just cloned) so your new docs source will be absorbed into the parent repo. + +.Example +[source,shell] ---- rm -rf .git ---- + Now your new directory/files will appear as uncommitted additions to the parent project (`git status`). -. Run Bundler to install dependencies. +. *Run Bundler* to install dependencies. + +[source,shell] ---- bundle ---- + 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. +. *Rename this README* so the upcoming _init_ operation does not overwrite it. + .Example +[source,shell] ---- mv README.adoc README.meta.adoc ---- + +[NOTE] This file may confuse future users; we advise removing it before sharing your LDCMF project. -. Edit your project metafile. +. *Edit the metafile* for your new LDCMF project. + 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. +. *Initialize your custom environment.* +[lowerroman] +.. Generate an _initialization config_ based on the custom preferences in `meta.yml`. + +[source,shell] +---- +bundle exec liquidoc --template _init/templates/init.yaml --data data/meta.yml --output _init/init.yml +---- ++ +This command performs a one-off template parsing to establish the temporary _init_ config file, responding with a message that your `_init/init.yml` was built. + +.. Generate _infrastructure files_ using your temporary init config. ++ +[source,shell] ---- bundle exec liquidoc -c _init/init.yml ---- + -This procedure customizes a few starter files based on `meta.yml`. +This procedure builds starter files (and inflates directories). +If your initialization steps proceeded without errors, you now have a codebase that serves as the skeleton for an LDCMF implementation, starting with a `_configs/` directory containing LiquiDoc, Asciidoctor, and Jekyll config files, as well as new `README.adoc` and `content/index.adoc` files. +You can make changes to `data/meta.yml` and re-run the liquidoc commands until you approve of the results. + +=== Build the Docs + +. You can now *review the new `README.adoc`* file generated by this procedure. + +The new README file is oriented toward _your LDCMF application's_ future users. +You should maintain it as the canonical reference for working with your docs codebase. -. You can now review your `README.adoc` and `content/index.adoc` files, editing and populating them with custom content. +. *Perform the first build of your seedling docset*, as instructed in the new README. + +Check the target directory for built artifacts and review them for errors. -. Delete or move the `README.meta.adoc` file (this file) and the `_init/` directory, which you will no longer need. +=== Wrapup -Further instructions are in your new README! -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. +. When you're certain everything looks good, *delete the `_init/` directory*. + +. Move or remove `README.meta.adoc` (likely this file!). + +Everything important from this file is available in the link:{ldcmf_site_base_url}/liquidoc-cmf-guides/admin[LDCMF Guides]. +// end::bootstrap-steps[] + +[TIP] +If you are not happy with the output, you may continue running the `bundle exec liquidoc -c _init/init.yml` command to overwrite the generated files. == Structure -This is the basic file directory structure of an initial LiquiDoc CMF project). +Here is the basic directory structure of an initial LiquiDoc CMF project once the first build procedure has been carried out. [source] ---- -liquidoc-cmf/ +├── _build/ ├── _configs/ -│ ├── asciidoctor.yml -│ └── build-docs.yml -├── data/ -│ └── meta.yml +│   ├── asciidoctor.yml +│   ├── build-docs.yml +│   └── jekyll-global.yml ├── _templates/ -│ └── liquid/ -│ └── company.asciidoc -├── content/ -│ ├── assets/ -│ ├── includes/ -│ ├── pages/ -│ ├── topics/ -│ └── index.adoc -└── theme/ -README.adoc -Gemfile +│   └── liquid/ +├── content +│   ├── assets/ +│   │   └── images/ +│   ├── pages/ +│   ├── snippets/ +│   └── topics/ +├── data/ +│   ├── meta.yml +│   ├── products.yml +│   └── schema.yml +├── theme/ +│   ├── css/ +│   ├── fonts/ +│   ├── / +│   │   ├── _includes/ +│   │   └── _layouts/ +│   ├── js/ +│   └── pdf-theme.yml +├── Gemfile +├── Gemfile.lock +├── LICENSE +└── README.adoc ---- +// tag::architecture-definitions[] +_build/:: +This is where all processed files end up, including all migrated assets, prebuilt source, or final artifacts. +This directory is _not_ tracked in source control, so you will not see it until you run a build routine, and you cannot commit changes made to it. +It is always safe to delete this directory in your local workspace. +We will explore the `_build/` directory more fully later. + +ifdef::guide_admin[] +_configs/:: +This folder is where the brains go. +The `build-docs.yml` config file belongs here, as does anything that is more about programming the build procedure than about informing the content. +The `asciidoctor.yml` file is for non-content AsciiDoc attributes that pertain to the structure or process of rendering with Asciidoctor. +This is also the home of various Jekyll configuration files, usually one for each guide and one for each guide type (e.g., `attributes-portal.yml` and `attributes-manual.yml`). +endif::guide_admin[] + +_ops/:: +This is a secondary “configs” location, for utilities and routines that support the _use_ of LDCMF by admins and documentarians. +For instance, the `init-topic.yml` config instructs the creation of topic files and schema entries. + +_templates/liquid/:: +Here we store most of our prebuilding templates. +These are _not_ Jekyll theming templates. +These are the ones we use for generating new YAML and AsciiDoc source files from other source files and external data. + +content/:: +The first of our publishable directories, `content/` is the base path for documentarians' main work area. +Everything inside the `content/` directory will be copied into the `_build/` directory early in the build process. + +content/assets/::: +For content assets, rather than theming assets. +If it illustrates your product, it probably goes here. +If it brands your company, it probably goes in `theme/assets/`. + +content/pages/::: +For AsciiDoc files of the _page_ content type. + +content/snippets/::: +For content _snippets_. + +content/topics/::: +For AsciiDoc files of the core _topic_ content type. + +data/:: +All YAML small-data files that contain content-relevant information go here. +These data files differ from those that belong in `_configs/` (or `_ops/`) in important ways, essentially revolving around whether the data needs to be available for display. +If it is not establishing settings or used to inform non-build functions (like in `_ops/`), the data file probably belongs in `data/`. +Let's look at some key data files standard to LDCMF. + +data/meta.yml::: +For general information about your company, URL and path info. +This file usually contains just simple data: a big (or small) column of basic key-value pairs to create simple variables. + +data/products.yrml::: +For subdivided information about your products in distinct blocks. +Each block can be called for selective ingest during build routines using the colon signifier, such as by calling `data/products.yml:product-1`, where `product-1:` is a top-level block in the `products.yml` file. + +data/guides.yml::: +This block is for content-oriented data that is distinct between the different portals or guides you're producing. +This is often redundant to your `products.yml` file, if product editions themselves are the major point of divergence in your docs, and it is formatted the same way. +For _this project_ (LDCMF Guides), the _guides_ are oriented toward _audiences_ (documentarians, admins, and developers), but the products (LiquiDoc and LDCMF) are distinct from this and actually documented/instructed _together_ in each guide. ++ +[TIP] +Favoring the filename `products.yml` is conventional when products and guides (portals) have a 1:1 relationship and `guides.yml` file is superfluous. + +data/manifest.yml::: +This crucial file provides a central manifest of all page-forming content items (pages, topics). +It dictates how they are organized in the site navigation (using metadata such as categories into which content items fall). +The schema file carries essential build info that lets us see relationships between topics and build content-exclusive portals from otherwise-decontextualized repositories. +Sometimes `data/schema.yml`, deprecated in favor of `manifest.yml`. + +data/terms.yml::: +By no means a required file, `terms.yml` is a great example of a file that is really just for content. +You can have as many of these key-value files, serving whatever purposes you wish. + +products/:: +This is an optional path for LDCMF projects. +If you plan to embed your product repos as submodules, put them in the `products/` directory. +Submodules are like shortcuts to those embedded repositories -- if you navigate into them, you can perform Git operations. +Submodules are typically used to ensure product repos are reliably available and properly checked out, generally in order to support migrating files into the build directory. + +theme/:: +All the files that structure your output displays go here. +This mainly includes Jekyll templates (`themes//_includes/` and `themes//_layouts/`) and asset files such as stylesheets, front-end javascripts, and of course theme-related images. +This would also be the home of PDF and slideshow output theme configurations, as applicable. + +theme/pdf-theme.yml::: +A very basic PDF theming file based on Asciidoctor's link:https://github.com/asciidoctor/asciidoctor-pdf/blob/master/data/themes/default-theme.yml[*default-theme.yml*], just to get you started. +For more about PDF theming, see the link:https://github.com/asciidoctor/asciidoctor-pdf/blob/master/docs/theming-guide.adoc[Asciidoctor PDF Theming Guide]. +// end::architecture-definitions[] + +== Build Config + +The `_configs/build-docs.yml` file is the brains of any LDCMF application. +It defines the sequential compilation routine and ensures all assets are in place for the final artifact rendering operations. + +=== LDCMF Build Strategies +// tag::build-strategies[] +The strength of LiquiDoc CMF its ability to maintain strictly “DRY” single sourcing while still producing diverse output. +These strategic principles are key to maintaining this capability. + +Store small data in flat files.:: +When we talk about _product metadata_, we are referring to information _about_ a software product, not any kind of data stored by that product. +Consider what data matters about products: capacities, dependencies, options, integrations, and anything classifiable as metadata, including information about the product developer. +Then consider how these things change as products evolve -- every version has its own array of the above attributes, and the list can only be expected to grow and morph. +Data of this kind is -- *small data* -- *is not best stored in relational databases*; version control is essential and schemas get in the way, especially since none of the data is served live. +If you want to keep your product info in Git, use appropriate flat-file formats for various representations. +The human-friendliest formats are probably *YAML* and *CSV*. +YAML can be edited in any decent code editor, and a comma-separated values file can be edited in any spreadsheet application. + +Share product data with the product.:: +Ideally, that small data stored in flat files should be kept in one canonical place, from which it is read by the docs and the product build routines, ensuring docs references reflect the current truth about the product. + +Prebuild and include complex reference content.:: +All that small data needs to make it into your docs in a more human-readable format. +This is where prebuilding reference content to AsciiDoc source comes in. +Use Liquid templates to generate includable AsciiDoc files into the `_build/snippets/` directory. +Then include them into your static AsciiDoc files. + +Handle major divergence by configuring output into “guides”.:: +When there are major points of divergence in output requirements -- such as significantly different “editions” of the same product or highly variant audiences, like basic vs advanced users or consumers vs developers -- each splinter necessitates its own _guide_. +In these cases, you want to direct users to the appropriate docset, as well as make it easy for those who land in the wrong guide to switch to a similar place in the parallel guide. +Guides are built sequentially, each drawing configuration settings and content designated for it, along with content and data common to other guides. +This process generates parallel guides, including Web portals that are built side by side and served as components of one site. + +Handle output-format diversity with “portals” and “manuals”.:: +A lot of the conflict in documentation output stems from the manuals vs portals debate. +Modern websites tend to work best by presenting content in semi-serialized or unserialized article format, more like Wikipedia than a book. +Meanwhile, technical documentation is often still intended to be consumed more like a book or a traditional manual. +LDCMF tries to balance both without requiring either, but each final rendering action is technically building either a book-style _manual_ or a help-site/wiki-style _portal_. ++ [NOTE] -Empty directories (ex., `content/assets/`) must be manually added. +.Coming Soon +JavaScript-driven slide presentations! + +[[rule-no-built-files]] +Maintain no built files in source control.:: +If a file is the product of data from other source files, generate that file at build time, and do not commit it to source. +This means keeping an ignored build directory (conventionally `_build/`), and everything outside that path should be unique. ++ +[NOTE] +Exceptions to this rule include _init_ and _ops_ routines, configured to instruct LiquiDoc to generate useful files. +The rule pertains to content files generated at build time, not files manually generated during setup or while creating new content. + +Keep functional code out of AsciiDoc source:: +Perform heavy processing up front as prebuilding, then include those prebuilt files during render phases. +While jekyll-asciidoc enables Liquid preprocessing in AsciiDoc files, LDCMF prefers prebuilding so the generated files can service more than Jekyll builds. +// end::build-strategies[] == Contributing diff --git a/_configs/build-docs.yml b/_configs/build-docs.yml deleted file mode 100644 index 4ed06a8..0000000 --- a/_configs/build-docs.yml +++ /dev/null @@ -1,22 +0,0 @@ -# Move critical files to the temporary build directory -- action: migrate - source: content/ - target: _build/ - options: - inclusive: false # Duplicate the files without the content/ dir -- action: migrate - source: theme/ - target: build/ -- action: parse - data: data/meta.yml - builds: - - output: _build/includes/_built_company-info.adoc - template: _templates/liquid/company-info.asciidoc -# Render your publication with Asciidoctor -- action: render - source: _build/index.adoc - data: _configs/asciidoctor.yml - builds: - - output: _build/output/docs.html - properties: - files: data/meta.yml diff --git a/_init/init.yml b/_init/init.yml deleted file mode 100644 index c043330..0000000 --- a/_init/init.yml +++ /dev/null @@ -1,8 +0,0 @@ -- action: parse - data: - file: data/meta.yml - builds: - - output: README.adoc - template: _init/templates/init_readme.asciidoc - - output: content/index.adoc - template: _init/templates/init_index.asciidoc diff --git a/_init/templates/init.yaml b/_init/templates/init.yaml new file mode 100644 index 0000000..c4a8689 --- /dev/null +++ b/_init/templates/init.yaml @@ -0,0 +1,14 @@ +- action: parse + data: + file: data/meta.yml + builds: + - output: README.adoc + template: _init/templates/init_readme.asciidoc + - output: content/index.adoc + template: _init/templates/init_index.asciidoc + - output: {{project_config_dir}}/{{project_config_file}} + template: _init/templates/init_build-config.yaml + - output: {{project_config_dir}}/jekyll-global.yml + template: _init/templates/init_jekyll-global.yaml + - output: {{project_config_dir}}/asciidoctor.yml + template: _init/templates/init_asciidoctor.yaml diff --git a/_configs/asciidoctor.yml b/_init/templates/init_asciidoctor.yaml similarity index 79% rename from _configs/asciidoctor.yml rename to _init/templates/init_asciidoctor.yaml index 70b0386..962aff9 100644 --- a/_configs/asciidoctor.yml +++ b/_init/templates/init_asciidoctor.yaml @@ -1,4 +1,5 @@ # This file contains global Asciidoctor attributes imagesdir: assets/images +snippetsdir: ../snippets safe: 0 icons: font diff --git a/_init/templates/init_build-config.yaml b/_init/templates/init_build-config.yaml new file mode 100644 index 0000000..32df9e9 --- /dev/null +++ b/_init/templates/init_build-config.yaml @@ -0,0 +1,35 @@ +# Move critical files to the temporary build directory +- action: migrate + source: content/ + target: _build/ + options: + inclusive: false # Duplicate the files without the content/ dir +- action: migrate + source: theme/ + target: _build/ +# Prebuild includable files +- action: parse + data: data/terms.yml + builds: + - output: _build/snippets/_built_terms.adoc + template: _templates/liquid/terms.asciidoc +- action: parse + data: data/meta.yml + builds: + - output: _build/snippets/_built_company-info.adoc + template: _templates/liquid/company-info.asciidoc +# Render your publication with Asciidoctor +- action: render + source: _build/index.adoc + data: + - _configs/asciidoctor.yml + - data/meta.yml + builds: + - output: _build/docs/docs.html + doctype: book + - output: _build/docs/docs.pdf + doctype: book +# Migrations in preparation for deploy +- action: migrate + source: _build/assets/ + target: _build/docs/ diff --git a/_init/templates/init_index.asciidoc b/_init/templates/init_index.asciidoc index 1977d5d..5a475b8 100644 --- a/_init/templates/init_index.asciidoc +++ b/_init/templates/init_index.asciidoc @@ -1,5 +1,17 @@ -= {{product_common_name}} += {{ product_suite_name }} == Maker Info -include::includes/_built_company-info.adoc[] +include::snippets/_built_company-info.adoc[] + +:leveloffset: +1 + +include::pages/about.adoc[] + +include::topics/intro.adoc[] + +:leveloffset: -1 + += Appendices + +include::pages/jargon-guide.adoc[leveloffset=+1] diff --git a/_init/templates/init_jekyll-global.yaml b/_init/templates/init_jekyll-global.yaml new file mode 100644 index 0000000..be8c23e --- /dev/null +++ b/_init/templates/init_jekyll-global.yaml @@ -0,0 +1,28 @@ +# This is the Jekyll configuration file +title: {{product_suite_name}} Portals +description: The documentation for {{project_subjects_list}} +output: web +source: {{project_build_dir}} +host: 127.0.0.1 +port: {{local_serve_port}} +destination: site + +data_dir: data +plugins_dir: _plugins +layouts_dir: +includes_dir: +images_dir: assets/images +css_dir: theme/css +theme_common_dir: theme +js_dir: theme/js + +asciidoc: {} +asciidoctor: + safe: 0 + base_dir: :docdir +# Do NOT place attributes here when building with LiquiDoc +# They will be loaded from other external sources + + +# File management +encoding: "utf-8" diff --git a/_init/templates/init_readme.asciidoc b/_init/templates/init_readme.asciidoc index 955d027..5380391 100644 --- a/_init/templates/init_readme.asciidoc +++ b/_init/templates/init_readme.asciidoc @@ -1,48 +1,66 @@ -= {{product_common_name}} Documentation - -This documentation {{space_type}} uses a docs-as-code framework called link:https://github.com/briandominick/liquidoc-cmf[LiquiDoc CMF]. -Check it out for full instructions and links to demo projects. += {{ product_suite_name }} Documentation +// This AsciiDoc file must be rendered to be properly viewed. +// The easiest way to view it rendered is on GitHub at +// https://github.com/DocOps/liquidoc-cmf +// OR copy and paste these contents into +// https://asciidoclive.com +// BELOW is all AsciiDoc formatting: +// https://asciidoctor.org/docs/what-is-asciidoc/ +// +// Document attributes (variables) +:docs_build_command_basic: bundle exec liquidoc -c {{ project_config_dir }}/{{ project_config_file }} +// +// Document content +This documentation {{ space_type }} uses a docs-as-code framework called link:https://www.ajyl.org/liquidoc-cmf[LiquiDoc CMF]. == Overview This is just a boilerplate stub to get you up and going. Describe your documentation project here. -== Quickstart +== Docs Build + +=== Requirements + +. Ruby runtime environment +. Bundler package management for Ruby + +=== Quickstart + +This will get you up and running with our docs! + +==== Installation + {% if space_type == "repo" %} . Clone this repo. + -.... -git clone {{ git_repo_uri }} -.... +[source,shell] +---- +git clone {{ project_git_repo_origin_uri }} {{ project_root_dir }} +---- {% endif %} -. Change to the proper directory. + +. Change to the proper working directory. + -.... -cd {% if project_root %}{{ project_root }}{% else %}my_project{% endif %}{% if space_type == "directory" %}/{{ docs_root_path }}{% endif %} -.... +[source,shell] +---- +cd {{ project_root_dir }}{%if subj_rel == "folder" %}/{{ docs_root_path }}{% endif %} +---- . Run Bundler to install dependencies. + -.... -bundle install -.... +[source,shell] +---- +bundle +---- + If Bundler is not installed, run `gem install bundler`, then repeat this command. -. Run your first docs build. -+ -.... -bundle exec liquidoc -c _configs/build-docs.yml -.... - -=== Requirements - -. Ruby runtime environment -. Bundler package management for Ruby - -== Build +==== Generation -To build, run `bundle exec liquidoc -c _configs/build-docs.yml`. +[source,shell,subs="+attributes"] +---- +{docs_build_command_basic} +---- -Check out the results in `_build/output/`. +This procedure generates files in the `_build/docs/` directory. diff --git a/_ops/init-topic.yml b/_ops/init-topic.yml new file mode 100644 index 0000000..0027d88 --- /dev/null +++ b/_ops/init-topic.yml @@ -0,0 +1,41 @@ +{%- assign slug_regex = "[a-z_\-]{7,50}" -%} +{%- assign slug_regex_esc = "[a-z_\-]\{7,50\}" -%} +{%- if vars.slug -%} + {%- assign slug_valid = vars.slug | regexreplace: slug_regex, "valid" -%} + {%- if slug_valid == "valid" -%} +- action: parse + builds: + - template: _templates/liquid/ops/topic.asciidoc + output: content/topics/{{vars.slug}}.adoc + variables: + slug: {{vars.slug}} + {%- if vars.parent %} + parent: true + {% endif %} + - template: _templates/liquid/ops/topic-entry.yaml + output: stdout + variables: + slug: {{vars.slug}} + {%- if vars.title %} + title: {{vars.title}} + {% endif -%} + {%- if vars.parent %} + parent: {{vars.parent}} + {% endif -%} + {%- else -%} +- action: parse + builds: + - template: _templates/liquid/ops/error.liquid + output: stdout + variables: + message: "Error: Slug must be between 7 and 50 characters and may only contain lowerase English letters, numerals, underscores (_), and hyphens (-)." + {%- endif -%} +{% else %} +# If we don't see a slug argument, +- action: parse + builds: + - template: _templates/liquid/ops/error.liquid + output: stdout + variables: + message: "Error: You must provide arguments for slug and title! Aborting..." +{% endif %} diff --git a/_templates/liquid/company-info.asciidoc b/_templates/liquid/company-info.asciidoc index 43fbcab..5aeeadb 100644 --- a/_templates/liquid/company-info.asciidoc +++ b/_templates/liquid/company-info.asciidoc @@ -1,3 +1,5 @@ {company_name_official} + {company_address_street} + {company_address_city}, {company_address_state} {company_address_zipcode} + +image::company_logo_big.png[] diff --git a/_templates/liquid/excludes.yaml b/_templates/liquid/excludes.yaml new file mode 100644 index 0000000..e1192bf --- /dev/null +++ b/_templates/liquid/excludes.yaml @@ -0,0 +1,23 @@ +# {% comment %} +# This template builds a list of paths for Jekyll to ignore +# +# Expected parameters: +# guide - (string) a guide slug, to indicate current guide +# {% endcomment %} +# File source: _templates/liquid/excludes.yaml +# Informs Jekyll what not to render +exclude: + - assets/ + - theme/ + - snippets/ + - site/ +{% if vars.guide %} +# Below this line all data is dynamically generated +{% assign keep_topics = topics | where_exp: "item","item.guides contains vars.guide" -%} +{%- assign keepers = keep_topics | map: "slug" -%} +{%- for story in topics -%} +{% unless keepers contains story.slug %} + - topics/{{ story.slug }}.adoc +{%- endunless -%} +{% endfor %} +{% endif %} diff --git a/_templates/liquid/ops/error.liquid b/_templates/liquid/ops/error.liquid new file mode 100644 index 0000000..22d6af2 --- /dev/null +++ b/_templates/liquid/ops/error.liquid @@ -0,0 +1,5 @@ +{% if vars.message %} +Whoops! {{vars.message}} +{% else %} +This error message lacks a 'message:'! +{% endif %} diff --git a/_templates/liquid/ops/topic-entry.yaml b/_templates/liquid/ops/topic-entry.yaml new file mode 100644 index 0000000..1ea96c2 --- /dev/null +++ b/_templates/liquid/ops/topic-entry.yaml @@ -0,0 +1,7 @@ +- slug: {{vars.slug}} + {%- if vars.title %} + title: {{vars.title}} + {%- endif -%} + {%- if vars.parent %} + subtopics: + {% endif -%} diff --git a/_templates/liquid/ops/topic.asciidoc b/_templates/liquid/ops/topic.asciidoc new file mode 100644 index 0000000..35169d1 --- /dev/null +++ b/_templates/liquid/ops/topic.asciidoc @@ -0,0 +1,5 @@ +include::{topic_page_meta}[tags="{{vars.slug}}"] +{%- if vars.parent %} + +include::../snippets/_built_container_{prod-slug}.adoc[tags="{{vars.slug}}"] +{% endif -%} diff --git a/_templates/liquid/page-meta.asciidoc b/_templates/liquid/page-meta.asciidoc new file mode 100644 index 0000000..3ee7b12 --- /dev/null +++ b/_templates/liquid/page-meta.asciidoc @@ -0,0 +1,21 @@ +{% assign these_topics = topics | where_exp: "item","item.guides contains vars.guide" %} +{% for story in these_topics %} +// tag::{{ story.slug }}[] +{%- capture guides -%} +{%- for r in story.guides -%}{{ r }}{%- unless forloop.last -%},{%- endunless -%} +{%- endfor -%}{%- endcapture -%} +{%- capture categories -%} +{%- for c in story.categories -%}{{- c -}}{%- unless forloop.last -%},{%- endunless -%} +{%- endfor -%}{%- endcapture -%} +{%- capture tags -%} +{%- for t in story.tags -%}{{ t }}{%- unless forloop.last -%},{%- endunless -%} +{%- endfor -%}{%- endcapture %} += {{ story.title }} +:page-title: {{ story.title }} +:page-permalink: {guide_site_path}/{{ story.slug }} +:page-guides: [{{ guides }}] +:page-categories: [{{ categories }}] +:page-tags: [{{ tags }}] +// end::{{ story.slug }}[] + +{% endfor %} diff --git a/_templates/liquid/sidebar.yaml b/_templates/liquid/sidebar.yaml new file mode 100644 index 0000000..c5e6104 --- /dev/null +++ b/_templates/liquid/sidebar.yaml @@ -0,0 +1,29 @@ +# expects vars.guide from build-docs.yml +{% assign guide = vars.guide %} +entries: +- title: Sidebar + levels: one + folders: +{%- for cat in categories -%} +{%- assign cat_found = false -%} +{%- assign cat_topics = topics | where_exp:"item","item.categories contains cat" -%} +{%- assign cat_role_topics = cat_topics | where_exp:"item","item.guides contains guide" -%} +{%- for story in cat_role_topics -%} +{%- unless cat_found -%} +{%- assign cat_found = true %} + - title: {{ cat | capitalize }} + output: web + folderitems: +{% if cat == "setup" %} + - title: Portal Overview + url: home + output: web +{% endif -%} +{%- endunless -%} +{%- assign this_title = story.title -%} +{%- if story.title_short -%}{%- assign this_title = story.title_short -%}{%- endif %} + - title: {{ this_title }} + url: {{ story.slug }} + output: web +{% endfor -%} +{%- endfor -%} diff --git a/_templates/liquid/terms.asciidoc b/_templates/liquid/terms.asciidoc new file mode 100644 index 0000000..6f26575 --- /dev/null +++ b/_templates/liquid/terms.asciidoc @@ -0,0 +1,6 @@ +{% for t in terms %} +// tag::{{ t.term | slugify }}[] +{{t.term}}:: +{{t.def}}{% if t.ref %} link:{{ref}}[(Resource)]{% endif %} +// end::{{ t.term | slugify }}[] +{% endfor %} diff --git a/_templates/liquid/topnav.yaml b/_templates/liquid/topnav.yaml new file mode 100644 index 0000000..1d89648 --- /dev/null +++ b/_templates/liquid/topnav.yaml @@ -0,0 +1,34 @@ +## Topnav single links +## if you want to list an external url, use external_url instead of url. the theme will apply a different link base. +topnav: +- title: Topnav + items: + - title: GitHub + external_url: {{ ldcmf-guides_github_project_url }} + +#Topnav dropdowns +topnav_dropdowns: +- title: Topnav dropdowns + folders: + - title: External Help + folderitems: + - title: Jekyll Documentation Theme + external_url: https://github.com/tomjoht/documentation-theme-jekyll + - title: LiquiDoc + external_url: {{liquidoc_landing_url}} + - title: LiquiDoc CMF + external_url: {{liquidoc-cmf_landing_url}} + - title: Asciidoctor User Manual + external_url: http://asciidoctor.org/docs/user-manual/ + - title: Jekyll Docs + external_url: https://jekyllrb.com/docs/home/ + - title: Shopify Liquid Docs + external_url: https://shopify.github.io/liquid/ + - title: LDCMF Guides + folderitems: + - title: DocPro Portal + external_url: {{docpro_portal_url}} + - title: Admin Portal + external_url: {{admin_portal_url}} + - title: Developer Portal + external_url: {{dev_portal_url}} diff --git a/_templates/liquid/xref-attributes.yaml b/_templates/liquid/xref-attributes.yaml new file mode 100644 index 0000000..58c73cb --- /dev/null +++ b/_templates/liquid/xref-attributes.yaml @@ -0,0 +1,13 @@ +# expects vars.guide, vars.type +# builds _built/data/built/xrefs_.adoc +{%- if vars.type == "portal" %}{%- assign pound = "#" -%}{%- endif -%} +{%- assign items = pages | concat: topics -%} +{%- for i in items -%} + {%- assign i_guides = "all" | split: "," -%} + {%- if i['guides'] -%} + {%- assign i_guides = i['guides'] -%} + {%- endif -%} + {%- if i_guides contains vars.guide or i_guides contains "all" %} +xref_{{ i.slug }}: "{{i.slug}}{{pound}},{{ i.title | replace: "&", "and" }}" + {% endif -%} +{%- endfor -%} diff --git a/content/assets/images/company_logo_big.png b/content/assets/images/company_logo_big.png new file mode 100755 index 0000000..6dc349c Binary files /dev/null and b/content/assets/images/company_logo_big.png differ diff --git a/content/assets/images/favicon.ico b/content/assets/images/favicon.ico new file mode 100644 index 0000000..0d505be Binary files /dev/null and b/content/assets/images/favicon.ico differ diff --git a/content/index.adoc b/content/index.adoc deleted file mode 100644 index e69de29..0000000 diff --git a/content/pages/about.adoc b/content/pages/about.adoc new file mode 100644 index 0000000..8a72542 --- /dev/null +++ b/content/pages/about.adoc @@ -0,0 +1,5 @@ += About These Docs + +This is boilerplate content to demonstrate a LiquiDoc CMF build. + +include::{snippetsdir}/snippets-misc.adoc[tags="meta-warning"] diff --git a/content/pages/jargon-guide.adoc b/content/pages/jargon-guide.adoc new file mode 100644 index 0000000..d4067f3 --- /dev/null +++ b/content/pages/jargon-guide.adoc @@ -0,0 +1,5 @@ += Jargon Guide + +This is the full list of specialized terms used in this product documentation. + +include::{snippetsdir}/_built_terms.adoc[] diff --git a/content/snippets/snippets-misc.adoc b/content/snippets/snippets-misc.adoc new file mode 100644 index 0000000..39fe6ab --- /dev/null +++ b/content/snippets/snippets-misc.adoc @@ -0,0 +1,6 @@ +// TIPS +// tag::meta-warning[] +[TIP] +Your docs still need a fair amount of work. + +// end::meta-warning[] diff --git a/content/topics/intro.adoc b/content/topics/intro.adoc new file mode 100644 index 0000000..1782ff7 --- /dev/null +++ b/content/topics/intro.adoc @@ -0,0 +1,3 @@ += Introduction to This Product + +This is an example first chapter. diff --git a/data/manifest.yml b/data/manifest.yml new file mode 100644 index 0000000..09fe5ae --- /dev/null +++ b/data/manifest.yml @@ -0,0 +1,74 @@ +# Optional file +# This is the clearinghouse datasource for content metadata +# Formerly data/schema.yml in some projects, manifest.yml +# is the central map or index file coordinating data +# when necessary. +# +# Its structure is like so: +# +# pages: +# - slug: some-page-slug +# title: Some Page Title +# title_short: A Page +# guides: [one,two] +# categories: [cat1,cat2,cat3] +# +# topics: +# - slug: some-topic-slug +# title: Some Topic Title +# title_short: A Topic +# guides: [one,two] +# subtopics: +# - another-topic +# - yet-another-topic +# - slug: another-topic +# title: A Child Topic of Some Topic Title +# title_short: A Topic's Kid +# guides: [one] +# - slug: yet-another-topic +# title: A Child of Some Topic Title +# title_short: A Topic's Kid +# guides: [two] +# +## In this example, two guides are being built +## ("one" and "two"). The page associated with +## some-page-slug will build for both guides, +## as will the first topic: some-topic-slug. +## However, each "child" of some-topic-slug will +## only build for one guide. The relationships +## will stay tracked for both. +## LDCMF can accommodate three tiers of nested +## topics in portal output. Guides will either +## 1. make child topic headers subordinate; +## 2. string all topics sequentially as peers; or +## 3. dump child topics into links to portal version +## 4. anything else you want to program +# +# +# categories: +# - slug: some-subject +# name: Some Broad Subject +# desc: Where we put stuff about Somes +# - slug: another-subject +# name: Another Broad Subject +# desc: Where we put stuff about Anothers +# domains: +# - slug: setup +# - name: Setup and Installation +# - slug: extending +# name: Extending the Product +# types: +# - slug: task +# key: t +# - slug: concept +# key: c +# - slug: reference +# key: r +# - slug: index +# key: i +# - slug: example +# key: x +# volumes: +## LiquiDoc Volumes are like Jekyll collections, only +## organized in the manifest rather than the file +## structure, for objective metadata. diff --git a/data/meta.yml b/data/meta.yml index a7797b1..93db6af 100644 --- a/data/meta.yml +++ b/data/meta.yml @@ -1,23 +1,73 @@ -company_name_official: We Make Code, Inc #REQUIRED -company_name_short: WEEEMC #REQUIRED (Can duplicate official) -product_common_name: BoxOdox #REQUIRED This is effectively the title of this docs project -git_repo_uri: git@github.com:DocOps/liquidoc-cmf.git #REQUIRED A proper git@ address like git@github.com:DocOps/liquidoc-cmf.git -space_type: repo #REQUIRED | -# Use 'directory' if part of a larger product repo -# Use 'repo' if docs are the whole repo -project_root: # The name of the root project directory, relative to the clone point -docs_root_path: # The relative path to docs dir relative to the project_root_path -# Leave docs_root_path blank if the space_type is 'repo' - -company_address_street: -company_address_city: -company_address_state: -company_address_zipcode: -git_repo_web_url: # The URL of your GitHub or other interface - -products: # leave this field blank - - name: # the name of the first product documented in this repo - slug: # lowercase alphanumeric and hyphens (-) only, ex. super-saas-premium -# Remove the leftmost # marks on subsequent lines to activate a new product record -# - name: # the name of the second product -# tagline: # a short description of the second product +# {% comment %} +# Required file +# This file establishes codebase configuration Settings +# plus general company and product data. +# It is used to generate AsciiDoc attributes. +# {% endcomment %} + +# This common meta file must remain "flat" -- only simple key/value pairs allowed +# Values may be boolean, string, numeric, or float -- no arrays or structures +project_name: Test Proj + +# The products/technologies documented by THIS docs project, as a phrase: +project_subjects_list: This, That, the Other Thing(TM) + +# The proper name for the products/technologies documented, as a phrase +# (may be same as project_subjects_list: +product_suite_name: The Things + +# An optional shorter version of product_suite_name: +product_suite_name_short: TheThings + +# The space_type refers to where/how THIS project resides, either: +# * repo | Docs have their own repository with no parent. +# * colo | Docs are collocated inside the product repository. +# Note: Docs with their own repo may contain product repos as submodules. +# For collocated (colo) setups, this project may have its own folder +# or reside in a submodule (subordinate repository). +space_type: repo + +# The subj_rel defines how THIS docs repo relates to the documented subjects: +# * parent | Products are all submodules of the docs (recommended) +# * submod | Docs are in a Git submodule subordinate to all product repos +# * folder | Docs are in a dir w/in the (solely documented) product repo. +# * none | The product repo and docs repo are technically unrelated. +# * mashup | It's complicated. +subj_rel: parent + +# THIS projet's git repo origin address +project_git_repo_origin_uri: git@github.com:yourghuname/test-project.git + +# The name of the root project directory, relative to the clone point +# By default this is the filename of your Git repo +# Ex: repo-name.git would have a project_root_dir: repo-name. +project_root_dir: test-project + +# The path to THIS project from repository root if space_type is 'colo' +# Leave blank if the project_root_dir is the entire docs dir +docs_root_path: + +# Location of THIS project's config files (LiquiDoc, Jekyll, Asciidoctor, etc): +project_config_dir: _configs + +# THIS project's LiquiDoc build configuration file: +project_config_file: build-docs.yml + +# The base directory into which prebuilding and final artifacts are generated +project_build_dir: _build + +# The local port at which your Jekyll development instance is served +# Conventionally in the 3000-4999 range; just avoid conflicting with +# any other running local HTTP server +local_serve_port: 4999 + +# The above entries will generate project_config +portals_base_path: portals + +# Company info +company_name_official: We Make Code, Inc +company_name_short: WEEEMC +company_address_street: 0 Nowhere Lane +company_address_city: Anywhereville +company_address_state: Puerto Rico +company_address_zipcode: 11111 diff --git a/data/terms.yml b/data/terms.yml new file mode 100644 index 0000000..7dc9197 --- /dev/null +++ b/data/terms.yml @@ -0,0 +1,28 @@ +terms: +- term: AJYL docstack + def: A combination of technologies (Asciidoctor, JAMstack/Jekyll, YAML, and Liquid) ideal for managing highly complex single-sourced technical documentation needs. + ref: https://ajyl.org + +- term: AsciiDoc + def: Dynamic, lightweight markup language for developing rich, complex documentation projects in flat files. + ref: http://asciidoctor.org/docs/user-manual + +- term: Asciidoctor + def: Suite of open source tools used to process AsciiDoc markup into various rendered output formats. + ref: http://asciidoctor.org + +- term: JAMstack + def: A combination of technologies that establish a “modern web development architecture based on client-side JavaScript, reusable APIs, and prebuilt Markup”. + ref: https://jamstack.org/ + +- term: Jekyll + def: A popular static-site generator capable of building entire websites out of AsciiDoc and YAML source, among other formats. + ref: https://jekyllrb.com/ + +- term: Liquid + def: Open source templating markup language maintained by Shopify. + ref: https://shopify.github.io/liquid/ + +- term: YAML + def: A slightly dynamic, semi-structured data format for key-value pairs and nested objects. + ref: http://searchitoperations.techtarget.com/definition/YAML-YAML-Aint-Markup-Language