mirror of
https://github.com/zaphar/ucg.git
synced 2025-07-21 18:10:42 -04:00
Update to new version of generator and theme.
This commit is contained in:
parent
214045f1a6
commit
d71182f017
@ -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
|
||||
|
||||
@ -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.
|
||||
|
||||
<style>
|
||||
th, td { padding: 1em; }
|
||||
th {
|
||||
background: black;
|
||||
color: white;
|
||||
}
|
||||
tbody td:nth-child(odd) {
|
||||
background-color: darkgrey;
|
||||
color: black;
|
||||
}
|
||||
|
||||
tbody td:nth-child(even) {
|
||||
background-color: lightgrey;
|
||||
color: black;
|
||||
}
|
||||
</style>
|
||||
<table>
|
||||
<thead><th></th><th>UCG</th><th>JSonnet</th><th>Dhall</th></thead>
|
||||
<tr>
|
||||
<td><b>Variables</b></td><td>x</td> <td>x</td><td>x</td>
|
||||
<tr>
|
||||
</tr>
|
||||
<td><b>Conditionals</b></td><td>x</td><td>x</td><td>x</td>
|
||||
<tr>
|
||||
</tr>
|
||||
<td><b>Functions</b></td><td>x</td><td>x</td><td>x</td>
|
||||
<tr>
|
||||
</tr>
|
||||
<td><b>Modules/Classes</b></td><td>x</td><td>x</td><td>x</td>
|
||||
<tr>
|
||||
</tr>
|
||||
<td><b>Imports</b></td><td>x</td><td>x</td><td>x</td>
|
||||
<tr>
|
||||
<tr>
|
||||
<td><b>Std Lib</b></td><td>Minimal</td><td>x</td><td>Prelude</td>
|
||||
</tr>
|
||||
</table>
|
||||
<table>
|
||||
|
||||
## JSonnet
|
||||
|
||||
<a href="https://jsonnet.org/learning/tutorial.html">Jsonnet</a> 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
|
||||
|
||||
<a href="https://github.com/dhall-lang/dhall-lang">Dhall-Lang</a> 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: <a href="/getting-started">Getting Started</a>
|
||||
2
docsite/site/themes/book/.gitignore
vendored
2
docsite/site/themes/book/.gitignore
vendored
@ -1,2 +0,0 @@
|
||||
.idea/
|
||||
public
|
||||
@ -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`:
|
||||
|
||||
|
||||
@ -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"
|
||||
|
||||
@ -8,7 +8,7 @@
|
||||
padding-bottom: 20px;
|
||||
transition: 0.5s;
|
||||
|
||||
.gutenberg-anchor {
|
||||
.zola-anchor {
|
||||
color: #4183c4;
|
||||
padding-left: 10px;
|
||||
text-decoration: none;
|
||||
|
||||
@ -14,7 +14,7 @@
|
||||
|
||||
<!-- CSS -->
|
||||
{% block css %}
|
||||
<link rel="stylesheet" href="{{ get_url(path="book.css", trailing_slash=false) | safe }}">
|
||||
<link rel="stylesheet" href="{{ get_url(path="book.css") | safe }}">
|
||||
{% endblock css %}
|
||||
|
||||
{% block extra_head %}
|
||||
@ -30,7 +30,8 @@
|
||||
<li><a href="/">Introduction</a></li>
|
||||
{% 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) %}
|
||||
<li {% if current_path == subsection.path %}class="active"{% endif %}>
|
||||
{% set chapter_num = loop.index %}
|
||||
<a href="{{ subsection.permalink }}">
|
||||
@ -101,10 +102,10 @@
|
||||
|
||||
{% block js_body %}
|
||||
{% if config.build_search_index %}
|
||||
<script type="text/javascript" src="{{ get_url(path="elasticlunr.min.js", trailing_slash=false) | safe }}"></script>
|
||||
<script type="text/javascript" src="{{ get_url(path="search_index.en.js", trailing_slash=false) | safe }}"></script>
|
||||
<script type="text/javascript" src="{{ get_url(path="elasticlunr.min.js") | safe }}"></script>
|
||||
<script type="text/javascript" src="{{ get_url(path="search_index.en.js") | safe }}"></script>
|
||||
{% endif %}
|
||||
<script type="text/javascript" src="{{ get_url(path="book.js", trailing_slash=false) | safe }}"></script>
|
||||
<script type="text/javascript" src="{{ get_url(path="book.js") | safe }}"></script>
|
||||
{% endblock js_body %}
|
||||
</body>
|
||||
|
||||
|
||||
@ -11,14 +11,8 @@
|
||||
<a class="previous" href="{{ page.lighter.permalink }}"><</a>
|
||||
{% 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 %}
|
||||
<a class="previous" href="{{ subsection.permalink }}"><</a>
|
||||
{% endif %}
|
||||
{% endfor %}
|
||||
{% endfor %}
|
||||
{% set parent = get_section(path=page.ancestors | reverse | first) %}
|
||||
<a class="previous" href="{{ parent.permalink }}"><</a>
|
||||
{% 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 %}
|
||||
<a class="next" href="{{ subsection.permalink }}">></a>
|
||||
{# no break #}
|
||||
|
||||
@ -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 %}
|
||||
<a class="next" href="{{ subsection.permalink }}">></a>
|
||||
{# no break #}
|
||||
|
||||
@ -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"
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user