Rearrange documentation and add "learn the workflow" section (eclipse…

…-langium#223)

* Add new documentation structure
* Add more about AST generation and reference resolution
* Add validations
* Collapse menu for better overview
* Expand on code generation
* Add testing code for user verification
* Fill further empty sites with life

hugo/config.toml

@@ -80,4 +80,7 @@ enableRobotsTXT = true
   # (Optional, default 'title') Configure how to sort file-tree menu entries. Possible options are 'title', 'linktitle',
   # 'date', 'publishdate', 'expirydate' or 'lastmod'. Every option can be used with a reverse modifier as well
   # e.g. 'title_reverse'.
-  #geekdocFileTreeSortBy = "title"
+  #geekdocFileTreeSortBy = "title"
+
+  geekdocCollapseSection = true
+  geekdocCollapseAllSections = true

hugo/content/docs/_index.md

@@ -1,12 +1,5 @@
 ---
 title: "Documentation"
-weight: 100
+weight: 0
 ---
-
-Langium is an open source language engineering tool with first-class support for the Language Server Protocol, written in TypeScript and running in Node.js.
-
-This reference documentation provides [an overview](/docs/langium-overview), a [getting started guide](/docs/getting-started) and a deep dive into several aspects of Langium. Additional topics are covered in [the Guides section](/guides/) and step-by-step walkthroughs are available in [the tutorials section](/tutorials/).
-
-## Want to contribute?
-
-Visit the [Langium repository](https://github.com/eclipse-langium/langium) to take part in improving Langium.
+<meta http-equiv="refresh" content="0; url=/docs/introduction/"/>

hugo/content/docs/introduction/_index.md

@@ -0,0 +1,25 @@
+---
+title: "What is Langium?"
+weight: -100
+---
+Langium is an open source language engineering tool with first-class support for the Language Server Protocol, written in TypeScript and running in Node.js.
+
+## Where to go from here?
+
+### Features
+
+If you need a more detailed list of Langium features, you can find them in the [features section](/docs/features).
+
+### Try it out
+
+If you want to see Langium in action, you can follow the [showcases](/showcase) or even the [playground](/playground).
+
+### Learn Langium
+
+If you are convinced by Langium and want to learn more about it, you can start with the [learn section](/docs/learn).
+
+### More details
+
+If you are looking for more details about Langium, you can find them in the [reference section](/docs/reference).
+
+If you are searching for a certain guide or recipe, you can find them in the [recipes section](/docs/recipes).

hugo/content/docs/langium-overview.md → hugo/content/docs/introduction/features.md

@@ -1,8 +1,8 @@
 ---
-title: "Langium Overview"
-weight: 0
+title: "Features"
+weight: 200
+url: /docs/features
 ---
-
 Designing programming languages from the ground up is hard, independent of whether your language is a "simple" domain specific language or a full-fledged general-purpose programming language.
 Not only do you have to keep up with the requirements of your domain experts, but you have to deal with all the technical complexity that comes with building a language, including questions such as:
 
@@ -14,11 +14,12 @@ This is the point where Langium comes into play. Langium aims to lower the barri
 
 In this chapter, you'll get a closer look at the requirements developers usually have to implement by themselves when building a programming language:
 
-- [Language parsing](#language-parsing)
-- [Semantic models](#semantic-models)
-- [Cross references and linking](#cross-references-and-linking)
-- [Workspace management](#workspace-management)
-- [Editing support](#editing-support)
+- [Language Parsing](#language-parsing)
+- [Semantic Models](#semantic-models)
+- [Cross References and Linking](#cross-references-and-linking)
+- [Workspace Management](#workspace-management)
+- [Editing Support](#editing-support)
+- [Try it out!](#try-it-out)
 
 Langium provides out-of-the-box solutions for these problems, with the ability to fine-tune every part of it to fit your domain requirements.
 

hugo/content/docs/introduction/playground.md

@@ -0,0 +1,5 @@
+---
+title: "Try it out!"
+weight: 400
+---
+<meta http-equiv="refresh" content="0; url=/playground"/>

hugo/content/docs/introduction/showcases.md

@@ -0,0 +1,5 @@
+---
+title: "Showcases"
+weight: 300
+---
+<meta http-equiv="refresh" content="0; url=/showcase"/>

hugo/content/docs/learn/_index.md

@@ -0,0 +1,6 @@
+---
+title: "Learn Langium"
+weight: 0
+url: /docs/learn
+---
+<meta http-equiv="refresh" content="0; url=/docs/learn/worflow/"/>

hugo/content/tutorials/_index.md → hugo/content/docs/learn/minilogo/_index.md

@@ -1,5 +1,5 @@
 ---
-title: "Tutorials"
+title: "Minilogo tutorial"
 weight: 200
 ---
 

hugo/content/docs/learn/workflow/_index.md

@@ -0,0 +1,80 @@
+---
+title: "Langium's workflow"
+weight: 0
+url: /docs/learn/worflow
+---
+
+Langium's workflow can be expressed as a flow chart diagram, which boils down to the following steps in the diagram.
+Be aware of the fact that the possibilities go beyond this simple workflow. For more advanced topics, you can find answers in the [recipes](/docs/recipes).
+
+{{<mermaid>}}
+flowchart TD
+  A(["1. Install Yeoman"]);
+  B(["2. Scaffold a Langium project"]);
+  C(["3. Write the grammar"]);
+  D(["4. Generate the AST"]);
+  E(["5. Resolve cross-references"]);
+  F(["6. Create validations"]);
+  G(["7. Generate artifacts"]);
+  H(["Find advanced topics"]);
+  A --> B --> C --> D --> E --> F --> G ~~~ H;
+  G -- for each additional\ngrammar change --> C;
+
+  click A "/docs/learn/workflow/install"
+  click B "/docs/learn/workflow/scaffold"
+  click C "/docs/learn/workflow/write_grammar"
+  click D "/docs/learn/workflow/generate_ast"
+  click E "/docs/learn/workflow/resolve_cross_references"
+  click F "/docs/learn/workflow/create_validations"
+  click G "/docs/learn/workflow/generate_everything"
+  click H "/docs/recipes"
+{{</mermaid>}}
+
+## Explanation
+
+This is the workflow we recommend for developing a language with Langium. It is a step-by-step guide that will help you to get started with Langium and to understand the basics of language development.
+
+This simple introduction can be seen as three main parts:
+
+* setting up your project environment (1.+2.): this is only done once
+* specifying the language features (3.-7.): this cycle you need to go through for each grammar change
+* everything advanced (8.): The limit of the common workflow is reached here. For specific questions you can find answers in the [recipes](/docs/recipes).
+
+While the first part is straight-forward, the last part is about advanced topics that differ from project to project.
+The middle part will be explained briefly in the following section.
+
+## Initial setup
+
+### [1. Install Yeoman](/docs/learn/workflow/install)
+
+This step ensures that you start a Langium project with the Yeoman generator. Yeoman is a scaffolding tool that helps you to start a new project with a predefined structure.
+
+### [2. Scaffold a Langium project](/docs/learn/workflow/scaffold)
+
+After installing Yeoman, you can scaffold a new Langium project.
+
+## Core workflow
+
+### [3. Write the grammar](/docs/learn/workflow/write_grammar)
+
+The first step in the core workflow starts with the grammar. You will have some language feature in mind that you want to implement. The grammar is used to nail down the syntax of your features. You can use our Langium VS Code extension to get syntax highlighting and code completion for `.langium` files. If your grammar is free of errors, you can generate the files for the _abstract syntax tree (AST)_.
+
+### [4. Generate the AST](/docs/learn/workflow/generate_ast)
+
+The AST is the backbone of your language. It is used to represent the structure of your language elements. The AST is generated from the grammar. One important part of the AST are the _cross-references_. They are used to resolve references between language elements. If you have cross-references in your language, you need to _resolve_ them, after this step. The actual generation is done by a call of the Langium CLI.
+
+### [5. Resolve cross-references](/docs/learn/workflow/resolve_cross_references)
+
+The cross-references are used to resolve references between language elements (between different sub trees of one file or even elements of other files(!)). This step is quite important, because it is the basis for the next steps. You can also see it like this: Step 4 will generate an AST with gaps, this fifth step will fill these gaps.
+
+### [6. Create validations](/docs/learn/workflow/create_validations)
+
+From here we have a fully utilized AST. Now every input file that matches the syntax will be accepted. But we want to have more control over the input. We want to check if the input is semantically correct. This is done by creating _validations_. They are used to check the input against a set of rules. If the input does not match the rules, an error will be thrown.
+
+### [7. Generate artifacts](/docs/learn/workflow/generate_everything)
+
+Now you have a fully working language. You can generate whatever you want from the input. This can be code, documentation, or anything else. You can use the AST to traverse the input and generate the output.
+
+## [Find advanced topics](/docs/recipes)
+
+Everything that is out of the scope of the common workflow is covered in the recipes. Here you can find answers to specific questions or problems that you might encounter during the development of your language.