marko 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f907c502f514d2cd27122f2c2d6acf4e96c066515075c7b8df69b39c3022ee85
-  data.tar.gz: 075f639071daab8f53d56fec821196514f8c614c58b43b1cbc2306fc616f9f24
+  metadata.gz: 2c3511e83282f71094f00c81bd8d926df0b0b9ecd7fa90fe978111e4b2d51afb
+  data.tar.gz: 34810477d8a4449873eda8799ccd57f47726d35884c721d46e0c606119ca91c9
 SHA512:
-  metadata.gz: fcdf1096aec13270c9a87ed229feda55c81e95de4073b7de264cb8b42dcd66ca2031f643bba63b40c9db2da2e83e945b817866589e4ecb3e2abebb04e2592ad3
-  data.tar.gz: df5ea3a5f9cdc378aee2bbe8292b3dc3d0e033da11a676a8fcaa5b5c294f614b0e23609ac6a633c79e1725ee9af462be1849a780ff4d1b45f1158ed417601f4e
+  metadata.gz: 3f0c0838b0c0f7328d927664e56caf58f787175bd0aa9883700b6a12377c1483e979138f021f8d3588bc287131292e889d6af0cecebfd29780a83588cb2e8291
+  data.tar.gz: d7441f513814ad56d4c91cbd09ace4cdd56e5cbaef5598f15f15dbb66b2770eb54fab2fd1580920df1375ee0f1f6ec0427b4df52fb871f432a4fb50a591fc85e

data/CHANGELOG.md

@@ -1,5 +1,52 @@
+---
+title: Marko Changelog
+keywords:
+- ruby
+- markup-compiler
+...
+
 ## [Unreleased]
 
+- [ ] add order_index to Artifact?
+
+## [0.3.0] - 2023-11-22
+
+- changed `Markup::Compiler` for using collection instead of decorated object
+- changed `Markup::Decorator` for providing `#text` than combines header, props, and body
+- changed `default` and `custom` templates
+- fixed `rake marko:toc` for using `abort` instead of `return` for empty query
+- removed unused `id` from `marko.yml`
+
+## [0.2.4] - 2023-11-21
+
+- changed compiler for using `trim_mode: '%<>'` for ERB
+- changed decorator
+  - removed `?\n` in `#header`, `#body`
+  - changed `#meta` for returning original meta without system keys
+  - added `#props` for creating `meta` table
+  - added `alias :topic :header`
+- changed `tt/artifact.md.tt` for removing extra empty lines
+- added `tt/custom.md.tt` as an example of handling custom meta keys
+- added test for `tt/*.md.tt`
+
+## [0.2.3] - 2023-11-06
+
+- upgraded for Ruby 3.2
+- fixed `assets/init/Rakefile` for lost file extension
+- removed extra word from README
+
+## [0.2.2] - 2023-04-14
+
+- changed artifact filename into `bin/artifact.md`; fixed `README.md`
+- removed Psych object string from `marko.yml`
+- changed `TreeNode#belongs_to?`
+
+## [0.2.0] - 2023-02-11
+
+- added `$ marko samples` that copies samples into `.marko/samples`
+- fixed "Marko v0.1.3" error gem version
+- changed `$ marko demo`, now it copies demo into `.marko/demo`
+
 ## [0.1.0] - 2023-01-02
 
 - Initial release

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    marko (0.1.0)
+    marko (0.3.0)
 
 GEM
   remote: https://rubygems.org/
@@ -10,6 +10,7 @@ GEM
     rake (13.0.6)
 
 PLATFORMS
+  x64-mingw-ucrt
   x64-mingw32
   x86_64-linux
 
@@ -19,4 +20,4 @@ DEPENDENCIES
   rake (~> 13.0)
 
 BUNDLED WITH
-   2.4.1
+   2.4.5

data/README.md

@@ -1,4 +1,9 @@
-# Marko
+---
+title: Marko Readme
+keywords:
+- ruby
+- markup-compiler
+...
 
 Marko is a markup compiler that builds a tree from separated sources and compiles it into a single deliverable artifact.
 
@@ -26,12 +31,12 @@ To help you with task automation, Marko provides `Marko.assemble` for assembling
 
 ### Structure
 
-`marko new PROJECT` command will create a new marko project inside the `PROJECT` directory with following structure:
+`marko new PROJECT` command will create a new Marko project inside the `PROJECT` directory with following structure:
 
 - [bin/](bin/) - output folder for `build`
 - [bin/assets/](bin/assets/) - assets folder
 - [src/](src/) - markup sources
-- [tt/](tt/) - templates for `build`
+- [tt/](tt/) - compiler templates
 - [marko.yml](marko.yml) - project configuration
 - [Rakefile](Rakefile) - Rake automation file
 - [README.md](README.md) - this file
@@ -110,27 +115,25 @@ The TreeNode.body can include macros. The most helpful one is `[[reference.id]]`
 
 - `@@tree` substituted by the tree of references to all descendants of the current node, might be used for the table of contents;
 - `@@list` substituted by the list of references to node items;
-- `@@todo` will will skip text with the macro till the end of the line
+- `@@todo` will skip text with the macro till the end of the line
 - `@@skip` will skip the text after the macro
 
 ### Templates
 
-Marko uses templates placed under the `tt` folder to compile sources into artifacts. You can use and customize the default one or design your own for particular purposes. It's just pure ERB, where Marko enumerates TreeNodes and renders the node output.
+Marko uses templates placed under the `tt` folder to compile sources into artifacts. You can use and customize the default one or design your own for particular purposes. It's just pure ERB, where Marko renders collection of decorated TreeNodes.
 
 ```
-<%= @node.header %>
-<%= @node.meta   %>
-<%= @node.body   %>
+% @model.each do |node|
+<%= node.text %>
+% end
 ```
 
 The `marko.yml` configuration file sets the building process's default template and other default values.
 
 ```yml
---- !ruby/struct:Marko::Artifact
-id: ed863484-243f-4d46-8012-4b148f8c2910
-title: Marko Artifact
-template: tt/artifact.md.tt
-filename: tt/marko-artifact.md
+title: Artifact
+template: tt/default.md.tt
+filename: bin/artifact.md
 ```
 
 ### Automation

data/Rakefile

@@ -1,5 +1,10 @@
 # frozen_string_literal: true
 
+# require "rake"
+# require "sancho"
+# tasks, folders = Sancho.tasks
+# Rake.application.rake_require tasks, folders
+
 require "bundler/gem_tasks"
 require "rake/testtask"
 

data/STORY.md

@@ -0,0 +1,44 @@
+---
+title: Marko Story
+date: 2023-01-26
+...
+
+[Marko](https://github.com/nvoynov/marko) is the result of my ten-year journey with Ruby playing the Business Analyst role.
+
+## Childhood, 2012
+
+Somewhere in between 2011 and 2014 I was playing Software Engineer role in some BigKnownCo where my first and foremost working tool was Microsoft Word 2007. Requirements specifications and Architecture design documents Artifacts that I was mainly working on often consisted of one and more hundreds of pages and it was such a pain to deal with in MS Word which was the corporate standard.
+
+In simple words it just gone crazy on large documents, the program consumed all my RAM, document navigation was slow, the program simply stopped responding, which entailed restarting the process with a loss of changes; or even worse, the loss of style formatting that is invisible to the eye when you simply cannot see it that the formatting was lost somewhere on the 225th page.
+
+> So problem was clear "__The problem of__ the lack of simple reliable tools and approaches for writing software artifacts __affects__ technical writers who develop and manage the artifacts __the impact of which is__ they tend to choose.."
+
+And I come up with the idea to create something light, simple and reliable to eliminate the MS Word from my work experience once and for all. This time I was curious about using YAML for storing requirements just inside file system. And I regularly done some estimations and prioritization for requirements, so I decided that FPA, PERT, and Risk-Value prioritization will be valuable features here.
+
+It was my first serious diving into Ruby for few weeks. I succeeded in reading / writing YAML and even provided estimations algorithms. I fall in love with Ruby. But from user perspective (I was the user) it was complete failure. Writing YAML manually was just unforgivable but that time I was obsessed with the format.
+
+> YAML was chosen just because this days I dramatically reduced time for load configuration of my target service provisioning system, that stored its configuration tree in RDBMS that causes ~5 000 000 selects for reading and about the same number insert/update for writing. It just reduced to 20 000 instead of 5 000 000.
+
+## Adolescence, 2014 - 2015
+
+It took two years to return to the subject, I left that job in 2014 and got haft year off. This time I discovered Markdown and static site generators, and I decided on Markdown as my primary markup format, where each source is just a plain markdown file with some metadata excerpt.
+
+Things were going well and in a few months, I got something quite usable. Estimations algorithms were thrown out; markup sources were assembled in one artifact that was translated into HTML by Kramdown. I named it "Creq" for "console requirements" and since then I assembled all software artifacts in my own tool.
+
+## Youth, since 2015
+
+Using my tool daily on a regular basis I discovered Pandoc and then can translate my artifact into any supported format; provided more advanced artifact templates, and provided a few templates for different purposes (draft, customer deliverable, etc.), added macros for tree node body.
+
+This time I named my tool Clerq because it just was my regular tool - I started my day from `$ git checkout -b new_feature` and finished with merging the branch, assembling new requirements increment, and pushing into git for my development team.
+
+In 2018 I have read The Clean Architecture I took my first clumsy attempts to apply it for Clerq.
+
+## Marko, 2022
+
+The last time I used Clerq for two months in July 2022. I noticed that time that I use only "create a new project" and "build the artifact" commands. And I realized that there is nothing about requirements - just about artifact assembling.
+
+So I took two weeks and finished 2022 with a git commit on Dec 31, 2022 :)
+
+The Marko purpose is assembling markup artifact from separated markup sources. Its interfaces are simple and clear. It could be naturally extended through Rakefile for any specific purpose related to visiting artifacts tree nodes.
+
+This is the first time I feel for a product that there are nothing I want to take or change. Just "Right Product, Done Right, Managed Messy"

data/_layouts/footer.md

@@ -0,0 +1,4 @@
+<div id="footer">
+  ***
+  © 2022-2023 <a href="http://nvoynov.github.io/">nvoynov</a>
+</div>

data/_layouts/header.md

@@ -0,0 +1,3 @@
+<p class="navbar">
+[ = **"Marko" Markup Compiler** = [Readme](readme.html) ~  [Changelog](changelog.html) ~ [Story](story.html) ~ [Github](https://github.com/nvoynov/sancho)]{.smallcaps}
+</p>

data/_layouts/layout.html

@@ -0,0 +1,73 @@
+<!DOCTYPE html>
+<html xmlns="http://www.w3.org/1999/xhtml" lang="$lang$" xml:lang="$lang$"$if(dir)$ dir="$dir$"$endif$>
+<head>
+  <meta charset="utf-8" />
+  <meta name="generator" content="pandoc" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes" />
+$for(author-meta)$
+  <meta name="author" content="$author-meta$" />
+$endfor$
+$if(date-meta)$
+  <meta name="dcterms.date" content="$date-meta$" />
+$endif$
+$if(keywords)$
+  <meta name="keywords" content="$for(keywords)$$keywords$$sep$, $endfor$" />
+$endif$
+$if(description-meta)$
+  <meta name="description" content="$description-meta$" />
+$endif$
+  <title>$if(title-prefix)$$title-prefix$ – $endif$$pagetitle$</title>
+  <style>
+    $styles.html()$
+  </style>
+$for(css)$
+  <link rel="stylesheet" href="$css$" />
+$endfor$
+$for(header-includes)$
+  $header-includes$
+$endfor$
+$if(math)$
+  $math$
+$endif$
+  <!--[if lt IE 9]>
+    <script src="//cdnjs.cloudflare.com/ajax/libs/html5shiv/3.7.3/html5shiv-printshiv.min.js"></script>
+  <![endif]-->
+</head>
+<body>
+$for(include-before)$
+$include-before$
+$endfor$
+$if(title)$
+<header id="title-block-header">
+<h1 class="title">$title$</h1>
+$if(subtitle)$
+<p class="subtitle">$subtitle$</p>
+$endif$
+$for(author)$
+<p class="author">$author$</p>
+$endfor$
+$if(date)$
+<p class="date">$date$</p>
+$endif$
+$if(abstract)$
+<div class="abstract">
+<div class="abstract-title">$abstract-title$</div>
+$abstract$
+</div>
+$endif$
+</header>
+$endif$
+$if(toc)$
+<nav id="$idprefix$TOC" role="doc-toc">
+$if(toc-title)$
+<h2 id="$idprefix$toc-title">$toc-title$</h2>
+$endif$
+$table-of-contents$
+</nav>
+$endif$
+$body$
+$for(include-after)$
+$include-after$
+$endfor$
+</body>
+</html>

data/_layouts/robots.txt.erb

@@ -0,0 +1,4 @@
+User-agent: *
+Allow: /
+
+Sitemap: https://<%= @site.domain %>/sitemap.xml

data/_layouts/sitemap.xml.erb

@@ -0,0 +1,20 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<urlset xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xsi:schemaLocation="http://www.sitemaps.org/schemas/sitemap/0.9 http://www.sitemaps.org/schemas/sitemap/0.9/sitemap.xsd"
+    xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+
+  <url>
+    <loc><%= @site.domain %>/</loc>
+    <lastmod><%= @site.pages_by_date.first.date %></lastmod>
+    <changefreq>weekly</changefreq>
+    <priority>1.0</priority>
+  </url>
+<% @site.pages.each do |page| %>
+  <url>
+    <loc><%= @site.domain %>/<%= page.url %></loc>
+    <lastmod><%= page.date %></lastmod>
+    <changefreq>weekly</changefreq>
+    <priority>0.8</priority>
+  </url>
+<% end %>
+</urlset>

data/_layouts/styles.css

@@ -0,0 +1,92 @@
+body {
+  margin: auto;
+  padding-right: 1em;
+  padding-left: 1em;
+  max-width: 44em;
+  color: black;
+  font-family: Verdana, sans-serif;
+  font-size: 100%;
+  line-height: 140%;
+  color: #333;
+}
+
+pre {
+  border: 1px dotted gray;
+  background-color: #ececec;
+  color: #1111111;
+  padding: 0.5em;
+}
+
+code {
+  font-family: monospace;
+  font-size: 140%;
+  color: #b34700;
+}
+
+h1 a, h2 a, h3 a, h4 a, h5 a {
+  text-decoration: none;
+  color: #7a5ada;
+}
+
+h1, h2, h3, h4, h5 {
+  font-family: verdana;
+  font-weight: bold;
+  border-bottom: 1px dotted black;
+  color: #7a5ada;
+}
+
+h1 {
+  font-size: 130%;
+}
+
+h2 {
+  font-size: 110%;
+}
+
+h3 {
+  font-size: 95%;
+}
+
+h4 {
+  font-size: 90%;
+  font-style: italic;
+}
+
+h5 {
+  font-size: 90%;
+  font-style: italic;
+}
+
+h1.title {
+  font-size: 200%;
+  font-weight: bold;
+  padding-top: 0.2em;
+  padding-bottom: 0.2em;
+  text-align: left;
+  border: none;
+}
+
+dt code {
+  font-weight: bold;
+}
+
+dd p {
+  margin-top: 0;
+}
+
+#footer {
+  padding-top: 1em;
+  font-size: 70%;
+  color: gray;
+  text-align: center;
+}
+
+.navbar {
+  background: #fff;
+  border-bottom: 1px solid #000;
+  margin: 0 0 1em;
+  padding: 1em 0;
+  position: sticky;
+  top: 0;
+  z-index: 100;
+}

data/docs/changelog.html

@@ -0,0 +1,74 @@
+<!DOCTYPE html>
+<html xmlns="http://www.w3.org/1999/xhtml" lang="" xml:lang="">
+<head>
+  <meta charset="utf-8" />
+  <meta name="generator" content="pandoc" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes" />
+  <meta name="keywords" content="ruby, markup-compiler" />
+  <title>Marko Changelog</title>
+  <style>
+    code{white-space: pre-wrap;}
+    span.smallcaps{font-variant: small-caps;}
+    div.columns{display: flex; gap: min(4vw, 1.5em);}
+    div.column{flex: auto; overflow-x: auto;}
+    div.hanging-indent{margin-left: 1.5em; text-indent: -1.5em;}
+    ul.task-list{list-style: none;}
+    ul.task-list li input[type="checkbox"] {
+      width: 0.8em;
+      margin: 0 0.8em 0.2em -1.6em;
+      vertical-align: middle;
+    }
+    .display.math{display: block; text-align: center; margin: 0.5rem auto;}
+  </style>
+  <link rel="stylesheet" href="css/styles.css" />
+  <!--[if lt IE 9]>
+    <script src="//cdnjs.cloudflare.com/ajax/libs/html5shiv/3.7.3/html5shiv-printshiv.min.js"></script>
+  <![endif]-->
+</head>
+<body>
+<p class="navbar">
+<span class="smallcaps">= <strong>“Marko” Markup Compiler</strong> = <a
+href="readme.html">Readme</a> ~ <a href="changelog.html">Changelog</a> ~
+<a href="story.html">Story</a> ~ <a
+href="https://github.com/nvoynov/sancho">Github</a></span>
+</p>
+<header id="title-block-header">
+<h1 class="title">Marko Changelog</h1>
+</header>
+<nav id="TOC" role="doc-toc">
+<ul>
+<li><a href="#unreleased" id="toc-unreleased">[Unreleased]</a></li>
+<li><a href="#section" id="toc-section">[0.2.0] - 2023-02-11</a></li>
+<li><a href="#section-1" id="toc-section-1">[0.1.0] -
+2023-01-02</a></li>
+</ul>
+</nav>
+<h2 id="unreleased">[Unreleased]</h2>
+<p>TODO</p>
+<ul>
+<li>custom code (Rakefile?)
+<ul>
+<li>FPA, PERT estimation sheets based on old gems</li>
+<li>“complexity” based on node incoming/outgoing links</li>
+<li>this might be helpful for estimations, some sort of adapted FPA in
+story points!</li>
+</ul></li>
+</ul>
+<h2 id="section">[0.2.0] - 2023-02-11</h2>
+<ul>
+<li>added <code>$ marko samples</code> that copies samples into
+<code>.marko/samples</code></li>
+<li>fixed “Marko v0.1.3” error gem version</li>
+<li>changed <code>$ marko demo</code>, now it copies demo into
+<code>.marko/demo</code></li>
+</ul>
+<h2 id="section-1">[0.1.0] - 2023-01-02</h2>
+<ul>
+<li>Initial release</li>
+</ul>
+<div id="footer">
+<hr />
+<p>© 2022-2023 <a href="http://nvoynov.github.io/">nvoynov</a></p>
+</div>
+</body>
+</html>

data/docs/css/styles.css

@@ -0,0 +1,92 @@
+body {
+  margin: auto;
+  padding-right: 1em;
+  padding-left: 1em;
+  max-width: 44em;
+  color: black;
+  font-family: Verdana, sans-serif;
+  font-size: 100%;
+  line-height: 140%;
+  color: #333;
+}
+
+pre {
+  border: 1px dotted gray;
+  background-color: #ececec;
+  color: #1111111;
+  padding: 0.5em;
+}
+
+code {
+  font-family: monospace;
+  font-size: 140%;
+  color: #b34700;
+}
+
+h1 a, h2 a, h3 a, h4 a, h5 a {
+  text-decoration: none;
+  color: #7a5ada;
+}
+
+h1, h2, h3, h4, h5 {
+  font-family: verdana;
+  font-weight: bold;
+  border-bottom: 1px dotted black;
+  color: #7a5ada;
+}
+
+h1 {
+  font-size: 130%;
+}
+
+h2 {
+  font-size: 110%;
+}
+
+h3 {
+  font-size: 95%;
+}
+
+h4 {
+  font-size: 90%;
+  font-style: italic;
+}
+
+h5 {
+  font-size: 90%;
+  font-style: italic;
+}
+
+h1.title {
+  font-size: 200%;
+  font-weight: bold;
+  padding-top: 0.2em;
+  padding-bottom: 0.2em;
+  text-align: left;
+  border: none;
+}
+
+dt code {
+  font-weight: bold;
+}
+
+dd p {
+  margin-top: 0;
+}
+
+#footer {
+  padding-top: 1em;
+  font-size: 70%;
+  color: gray;
+  text-align: center;
+}
+
+.navbar {
+  background: #fff;
+  border-bottom: 1px solid #000;
+  margin: 0 0 1em;
+  padding: 1em 0;
+  position: sticky;
+  top: 0;
+  z-index: 100;
+}