diff --git a/docsite/Makefile b/docsite/Makefile index fcc345b..ad24f44 100644 --- a/docsite/Makefile +++ b/docsite/Makefile @@ -24,7 +24,7 @@ content := $(shell find site/content -type f -iname *.md) site/.built: $(content) cd site; \ - gutenberg build -o generated + zola build -o generated touch site/.built gensite: site/.built diff --git a/docsite/site/content/_index.md b/docsite/site/content/_index.md index f2fe24a..f50baec 100644 --- a/docsite/site/content/_index.md +++ b/docsite/site/content/_index.md @@ -4,22 +4,122 @@ in_seach_index = true +++ [UCG](https://crates.io/crates/ucg) is a universal grammar for configuration. -It's goal is not to define a configuration format like JSON, YAML, or TOML. It -is not intended to replace the other configuration formats. Instead it is + +# Why another config format? + +That's a good question. The world certainly doesn't need another serialization +format for configuration values. We probably haven't really needed another +serialization format since `ini` files and `xml`. But now that we do have so +many to choose from people are choosing them right and left. + +Chances are if you manage more than 2 systems in your job then you have at +least 2 different serialization formats for their configuration. You probably +also have parts of that configuration that are shared between multiple systems +and need to be kept in sync between those different formats. + +You might also have standard configs for vm based languages or deployment +targets like kubernetes. You also probably have a configuration management +system and it probably has some form of templating support to meet all of those +needs. UCG is meant to solve the problems that the templating engine +introduces. + +Templates can be difficult to manage without introducing hard to see errors in +the serialization format they are generating. Most templating engines aren't +aware of the format they are templating. They usually end up being an ad-hoc +programming language in their own right but without any way to enforce +invariants or protect the template writer from creating bad configs. UCG +attempts to solve this problem by giving you a real programming language +that also generates the config format you need natively and safely. + +## UCG is not a config serialization format + +UCG's goal is not to define a configuration format like JSON, YAML, or TOML. It +is not intended to replace the other serialization formats. Instead it is intended to provide a common grammar for generating those formats. Currently -UCG is able to generate conversions for the following formats. +UCG is able to compile into a number of formats including: * Environment Variables -* Command Line Flags -* An executable shell launch script combining the two above +* An executable shell launch script * JSON * YAML * TOML +* XML -UCG allows you to use one common grammar to generate configuation values for any applications that -use one of provided conversion outputs while also allowing you to easily share common configuration -values like hostnames, jvm settings, and database settings. +## UCG is not a templating engine -UCG can build an entire directory of files or a single file. +UCG is not a templating language. It is a compiler whose targets are specific +serialization formats. As such it doesn't output invalid formats in, for +example, `json` or `yaml`. It allows you to check configurations against +schemas. It lets you use shared logic when assembling the datastructures that +your config format. + +UCG allows you to use one common grammar to generate configuation values for +any applications that use one of provided serialization formats while also +allowing you to easily share common configuration values like hostnames, jvm +settings, and database settings. + +UCG is designed to make configuration as code a first class citizen of your +deployment strategy. + +# UCG is not alone + +When I started UCG I was unaware of some other attempts at this that came before. If you find UCG intriguing you might be interested in these other projects with similar goals. + + + + + + + + + + + + + + + + + + + + + + +
UCGJSonnetDhall
Variablesx xx
Conditionalsxxx
Functionsxxx
Modules/Classesxxx
Importsxxx
Std LibMinimalxPrelude
+ + +## JSonnet + +Jsonnet is a project +from a Google employee that also has a programming language approach that +outputs to common formats. It has functions, shared libraries, a standard +library and more tool support than UCG currently has. + +JSonnet is probably the closest thing to UCG out there with some differences in +syntax but very similar semantics. + +## Dhall lang + +Dhall-Lang is a config +language with the interesting feature of being guaranteed to complete. It's a +pure functional language with functions, shared libraries and a standard +library as well. If a strong type system with a haskell like syntax are your +cup of tea then dhall lang is for you. Next: Getting Started \ No newline at end of file diff --git a/docsite/site/themes/book/.gitignore b/docsite/site/themes/book/.gitignore deleted file mode 100644 index 4139cd5..0000000 --- a/docsite/site/themes/book/.gitignore +++ /dev/null @@ -1,2 +0,0 @@ -.idea/ -public diff --git a/docsite/site/themes/book/README.md b/docsite/site/themes/book/README.md index f015188..6b54556 100644 --- a/docsite/site/themes/book/README.md +++ b/docsite/site/themes/book/README.md @@ -17,7 +17,7 @@ First download this theme to your `themes` directory: ```bash $ cd themes -$ git clone https://github.com/Keats/book.git +$ git clone https://github.com/getzola/book.git ``` and then enable it in your `config.toml`: diff --git a/docsite/site/themes/book/config.toml b/docsite/site/themes/book/config.toml index 191bf49..42544df 100644 --- a/docsite/site/themes/book/config.toml +++ b/docsite/site/themes/book/config.toml @@ -1,4 +1,4 @@ -base_url = "https://gutenberg-book.netlify.com" +base_url = "https://zola-book.netlify.com" compile_sass = true title = "book theme" description = "A book theme" diff --git a/docsite/site/themes/book/sass/_content.scss b/docsite/site/themes/book/sass/_content.scss index 541fad8..5a55ff6 100644 --- a/docsite/site/themes/book/sass/_content.scss +++ b/docsite/site/themes/book/sass/_content.scss @@ -8,7 +8,7 @@ padding-bottom: 20px; transition: 0.5s; - .gutenberg-anchor { + .zola-anchor { color: #4183c4; padding-left: 10px; text-decoration: none; diff --git a/docsite/site/themes/book/templates/index.html b/docsite/site/themes/book/templates/index.html index 1600fce..647c5a0 100644 --- a/docsite/site/themes/book/templates/index.html +++ b/docsite/site/themes/book/templates/index.html @@ -14,7 +14,7 @@ {% block css %} - + {% endblock css %} {% block extra_head %} @@ -30,7 +30,8 @@
  • Introduction
    • {% block menu %} {% set index = get_section(path="_index.md") %} - {% for subsection in index.subsections %} + {% for s in index.subsections %} + {% set subsection = get_section(path=s) %}
  • {% set chapter_num = loop.index %} @@ -101,10 +102,10 @@ {% block js_body %} {% if config.build_search_index %} - - + + {% endif %} - + {% endblock js_body %} diff --git a/docsite/site/themes/book/templates/page.html b/docsite/site/themes/book/templates/page.html index 524b661..ee368b2 100644 --- a/docsite/site/themes/book/templates/page.html +++ b/docsite/site/themes/book/templates/page.html @@ -11,14 +11,8 @@ {% else %} {# No page before, find the link for the section it's in if there is one #} - {% set index = get_section(path="_index.md") %} - {% for subsection in index.subsections %} - {% for p in subsection.pages %} - {% if p.permalink == page.permalink %} - - {% endif %} - {% endfor %} - {% endfor %} + {% set parent = get_section(path=page.ancestors | reverse | first) %} + {% endif %} {% endblock prev_link %} @@ -29,7 +23,8 @@ {# No page after, find the link for the following section #} {% set index = get_section(path="_index.md") %} {% set found_current = false %} - {% for subsection in index.subsections %} + {% for s in index.subsections %} + {% set subsection = get_section(path=s) %} {% if found_current %} {# no break #} diff --git a/docsite/site/themes/book/templates/section.html b/docsite/site/themes/book/templates/section.html index d8639c5..4079dda 100644 --- a/docsite/site/themes/book/templates/section.html +++ b/docsite/site/themes/book/templates/section.html @@ -10,7 +10,8 @@ if there isn't any pages in it #} {% set index = get_section(path="_index.md") %} {% set found_current = false %} - {% for subsection in index.subsections | reverse %} + {% for s in index.subsections | reverse %} + {% set subsection = get_section(path=s) %} {% if subsection.permalink == section.permalink %} {% set_global found_current = true %} {% else %} @@ -36,7 +37,8 @@ {# No page in the section, find the link for the following section #} {% set index = get_section(path="_index.md") %} {% set found_current = false %} - {% for subsection in index.subsections %} + {% for s in index.subsections %} + {% set subsection = get_section(path=s) %} {% if found_current %} {# no break #} diff --git a/docsite/site/themes/book/theme.toml b/docsite/site/themes/book/theme.toml index c780b74..64943cc 100644 --- a/docsite/site/themes/book/theme.toml +++ b/docsite/site/themes/book/theme.toml @@ -1,13 +1,13 @@ name = "book" description = "A book theme inspired from GitBook/mdBook" license = "MIT" -homepage = "https://github.com/Keats/book" -min_version = "0.4.0" -demo = "https://gutenberg-book.netlify.com" +homepage = "https://github.com/getzola/book" +min_version = "0.5.0" +demo = "https://zola-book.netlify.com" [extra] book_number_chapters = true [author] name = "Vincent Prouillet" -homepage = "https://vincent.is" +homepage = "https://www.vincentprouillet.com"