diff --git a/src/_includes/partials/description.html b/src/_includes/partials/description.html deleted file mode 100644 index b154a07..0000000 --- a/src/_includes/partials/description.html +++ /dev/null @@ -1,12 +0,0 @@ -
-

- kdl is a document language, mostly based on - SDLang, with xml-like semantics that looks - like you're invoking a bunch of CLI commands! -

- -

- It's meant to be used both as a serialization format and a configuration - language, and is relatively light on syntax compared to XML. -

-
diff --git a/src/_includes/partials/description.md b/src/_includes/partials/description.md new file mode 100644 index 0000000..22f2f5a --- /dev/null +++ b/src/_includes/partials/description.md @@ -0,0 +1,10 @@ +
+ +kdl is a document language, mostly based on +[SDLang](https://sdlang.org), with xml-like semantics that looks +like you're invoking a bunch of CLI commands! + +It's meant to be used both as a serialization format and a configuration +language, and is relatively light on syntax compared to XML. + +
diff --git a/src/_includes/partials/design-and-discussion.html b/src/_includes/partials/design-and-discussion.html deleted file mode 100644 index e653617..0000000 --- a/src/_includes/partials/design-and-discussion.html +++ /dev/null @@ -1,9 +0,0 @@ -
-

Design and Discussion

-

- kdl is still extremely new, and discussion about the format should happen - over on the - discussions page - in the Github repo. Feel free to jump in and give us your 2 cents! -

-
diff --git a/src/_includes/partials/design-and-discussion.md b/src/_includes/partials/design-and-discussion.md new file mode 100644 index 0000000..4d6d253 --- /dev/null +++ b/src/_includes/partials/design-and-discussion.md @@ -0,0 +1,10 @@ +
+ +## Design and Discussion + +kdl is still extremely new, and discussion about the format should happen +over on the +[discussions](https://github.com/kdoclang/kdl/discussions) page +in the Github repo. Feel free to jump in and give us your 2 cents! + +
diff --git a/src/_includes/partials/design-principles.html b/src/_includes/partials/design-principles.html deleted file mode 100644 index 9319dea..0000000 --- a/src/_includes/partials/design-principles.html +++ /dev/null @@ -1,18 +0,0 @@ -
-

Design Principles

-
    -
  1. Maintainability
    2. -
  2. Flexibility
    3. -
  3. Cognitive simplicity and Learnability
    4. -
  4. Ease of de/serialization
    5. -
  5. Ease of implementation
    6. -
- -

- These are the guiding principles behind the design of KDL, in order of - importance. These principles will hopefully be useful in tie-breaking and - otherwise directing specific decisions when it comes down to it. They are - intentionally vague when it comes to specifics, but more concrete - definitions for each one will be settled on as the project matures. -

-
diff --git a/src/_includes/partials/design-principles.md b/src/_includes/partials/design-principles.md new file mode 100644 index 0000000..7e730b5 --- /dev/null +++ b/src/_includes/partials/design-principles.md @@ -0,0 +1,17 @@ +
+ +## Design Principles + +1. Maintainability +1. Flexibility +1. Cognitive simplicity and Learnability +1. Ease of de/serialization +1. Ease of implementation + +These are the guiding principles behind the design of KDL, in order of +importance. These principles will hopefully be useful in tie-breaking and +otherwise directing specific decisions when it comes down to it. They are +intentionally vague when it comes to specifics, but more concrete +definitions for each one will be settled on as the project matures. + +
diff --git a/src/_includes/partials/overview.html b/src/_includes/partials/overview.md similarity index 74% rename from src/_includes/partials/overview.html rename to src/_includes/partials/overview.md index 9ad4f5c..33674a0 100644 --- a/src/_includes/partials/overview.html +++ b/src/_includes/partials/overview.md @@ -1,10 +1,10 @@
-

Overview

-

The basic syntax is similar to SDLang:

+## Overview - 
-    
+The basic syntax is similar to SDLang:
+
+```kdl
 // This is a node with a single string value
 title "Hello, World"
 
@@ -35,13 +35,11 @@ C style multiline
 */
 
 tag /*foo=true*/ bar=false
-    
-
+``` -

But kdl changes a few details:

+But kdl changes a few details: - 
-    
+```kdl
 // Files must be utf8 encoded!
 smile "😁"
 
@@ -94,20 +92,18 @@ mynode /-"commented" "not commented" /-key="value" /-{
   a
   b
 }
-    
-
+``` -

The following SDLang features are removed altogether:

+The following SDLang features are removed altogether: + +- "Anonymous" nodes +- Binary data literals +- Date/time formats +- `on` and `off` booleans +- Backtick strings +- Semicolons +- Namespaces with `:` +- Shell style (`#`) and Lua style (`--`) comments +- Distinction between 32/64/128-bit numbers. There's just numbers. -
diff --git a/src/index.html b/src/index.md similarity index 50% rename from src/index.html rename to src/index.md index 8d9f6d5..7402818 100644 --- a/src/index.html +++ b/src/index.md @@ -7,8 +7,7 @@ title: kdl - Kat's Document Language

kdl - Kat's Document Language

- -{% include partials/description.html %} -{% include partials/design-and-discussion.html %} -{% include partials/design-principles.html %} -{% include partials/overview.html %} +{% include partials/description.md %} +{% include partials/design-and-discussion.md %} +{% include partials/design-principles.md %} +{% include partials/overview.md %}