fix: chaptering system

Ph0enixKM · Ph0enixKM · commit 835a05cf4fcb · 2024-09-30T22:23:16.000+02:00
diff --git a/docs/advanced_syntax/advanced_syntax.md b/docs/advanced_syntax/advanced_syntax.md
@@ -1,3 +1 @@
-# Advanced Syntax
-
-In the subsequent section you will learn more about Amber syntax that is recommended for advanced Amber or Shell Script developers.
+In the subsequent section you will learn more about Amber syntax that is recommended for advanced Amber or Shell Script developers.
diff --git a/docs/advanced_syntax/as_cast.md b/docs/advanced_syntax/as_cast.md
@@ -1,5 +1,3 @@
-# As cast
-
 As cast is a tool that might initially seem like an easy way to convert types. So, why has this functionality found its place in the advanced category? Well, with great power comes great responsibility. You could perform some casts that make sense, like from `Bool` to `Num`, but you could also perform casts that we refer to as _absurd_. An example of this might be converting `Text` to `Num`.
 
 ## Regular casts
diff --git a/docs/advanced_syntax/builtins.md b/docs/advanced_syntax/builtins.md
@@ -1,6 +1,4 @@
-# Builtins
-
-Builtins are native methods (built in the compiler itself) and they are also reserved keywords in Amber.  
+Builtins are native methods (built in the compiler itself) and they are also reserved keywords in Amber.
 
 Similar to the standard library, they generate valid [Shellcheck](https://www.shellcheck.net/) code (though full support for this in Amber is still in progress).
 
@@ -22,7 +20,7 @@ echo "Hello World!"
 
 ## Mv
 
-If you need to move files you can use the `mv` builtin, requires two `Text` parameters.   
+If you need to move files you can use the `mv` builtin, requires two `Text` parameters.
 *Doesn't support the `mv` unix command parameters*.
 
 ```ab
@@ -38,7 +36,7 @@ mv "/tmp/a" "/tmp/b" failed {
 
 ## Nameof
 
-For more advanced commands, you might need the name of the variable in the compiled script. The `nameof` keyword provides this functionality.  
+For more advanced commands, you might need the name of the variable in the compiled script. The `nameof` keyword provides this functionality.
 
 For example, this allows you to perform operations like:
 
diff --git a/docs/advanced_syntax/compiler_flags.md b/docs/advanced_syntax/compiler_flags.md
@@ -1,5 +1,3 @@
-# Compiler Flags
-
 Compiler flags allow you to change the behavior of the compiler for the given scope of a function. Remember that some warnings are there for a reason. If you do not understand why some warning is being emitted, go ahead and learn more about basic syntax. Here is a list of all the compiler flags that are ready to be used:
 - `allow_nested_if_else` - Turns off the warning that encourages developer to use the syntax designed to handle if else chains.
 - `allow_generic_return` - Turns off the warning that tells user to specify a concrete return type when arguments with concrete types are used
@@ -11,4 +9,4 @@ Example:
 fun foo() {
 	// ...
 }
-```
+```
diff --git a/docs/advanced_syntax/type_condition.md b/docs/advanced_syntax/type_condition.md
@@ -1,5 +1,3 @@
-# Type condition
-
 Sometimes when building generic functions one could find it very convenient to additionally validate if passed value is one of the data types that are supported.
 
 ```ab
@@ -9,4 +7,4 @@ fun getObject(value) {
 		value is Num: getById(value)
 	}
 }
-```
+```
diff --git a/docs/basic_syntax/arrays.md b/docs/basic_syntax/arrays.md
@@ -1,5 +1,3 @@
-# Arrays
-
 We learned about array literals in the first chapter. In this chapter we will learn how to make use of them. Arrays are indexed from zero.
 
 To store or retrieve a value at a particular index of an array, you can use the following syntax:
diff --git a/docs/basic_syntax/basic_syntax.md b/docs/basic_syntax/basic_syntax.md
@@ -1,5 +1,3 @@
-# Basic Syntax
-
 > This language documentation assumes that you understand the basics of programming
 
 Since Amber was designed based on the ECMA script syntax some of the following parts of programming language may be familiar.
@@ -29,4 +27,4 @@ echo "My favorite fruits are:"
 loop fruit in fruits {
 	echo fruit
 }
-```
+```
diff --git a/docs/basic_syntax/commands.md b/docs/basic_syntax/commands.md
@@ -1,5 +1,3 @@
-# Commands
-
 The only way to access the bash shell is through Amber's commands. Commands can be used in the form of a statement or an expression.
 
 The important thing regarding commands is that they can `fail`. Failing is a new concept that forces the caller to handle the failure. There are many ways to handle failure:
@@ -88,7 +86,7 @@ silent unsafe {
 }
 ```
 
-## Unsafe command execution 
+## Unsafe command execution
 
 ```ab
 unsafe $test -d /path/to/file$
@@ -106,5 +104,3 @@ You can easily silent given command. Here is an example usage:
 ```ab
 silent $very loud command$
 ```
-
-
diff --git a/docs/basic_syntax/conditions.md b/docs/basic_syntax/conditions.md
@@ -1,5 +1,3 @@
-# Conditions
-
 There are three ways to perform conditional logic:
 - **If Statement** - This is a regular if statement that can be used anywhere
 - **If Chain** - This is _syntactical sugar_ for pesky if-else chained together.
@@ -100,4 +98,3 @@ The ternary expression can of course be inlined when the expressions inside are
 ```ab
 let candy = count > 1 then "candies" else "candy"
 ```
-
diff --git a/docs/basic_syntax/data_types.md b/docs/basic_syntax/data_types.md
@@ -1,5 +1,3 @@
-# Data types
-
 Amber supports 5 data types:
 - `Text` - The textual data type. In other programming languages it can also be called "string".
 - `Num` - The numeric data type. It's basically any number.
diff --git a/docs/basic_syntax/expressions.md b/docs/basic_syntax/expressions.md
@@ -1,5 +1,3 @@
-# Expressions
-
 We can combine our data type literals with operators. The operators only work on **the same** data type. For example adding `Text` to `Num` will cause in error and is an unsupported operation. If you want to merge multiple different values into one text, learn more here about [string interpolation](/basic_syntax/expressions#text-interpolation)
 
 ## Addition operator `+`
diff --git a/docs/basic_syntax/functions.md b/docs/basic_syntax/functions.md
@@ -1,5 +1,3 @@
-# Functions
-
 Functions can help you organize the structure of your code into reusable components. Here is how you can declare such function:
 
 ```ab
diff --git a/docs/basic_syntax/importing.md b/docs/basic_syntax/importing.md
@@ -1,5 +1,3 @@
-# Importing
-
 In Amber, you can import functions from other files. To make a function accessible from an external file, you need to declare it as _public_ within the file where it’s defined.
 
 ## Public Functions
@@ -85,4 +83,4 @@ main (args) {
 		echo "{i}: {arg}"
 	}
 }
-```
+```
diff --git a/docs/basic_syntax/loops.md b/docs/basic_syntax/loops.md
@@ -1,5 +1,3 @@
-# Loops
-
 Amber supports two types of loop:
 
 - **Infinite** loop that can only be broken with a `break` keyword
@@ -50,10 +48,3 @@ loop index, file in files {
 ```
 
 The above example will iterate through all the files in the array and index them according to their order in the array. As a result, these files will be renamed to `0config.json`, `1file.txt`, and `2audio.mp3`.
-
-
-
-
-
-
-
diff --git a/docs/basic_syntax/variables.md b/docs/basic_syntax/variables.md
@@ -1,5 +1,3 @@
-# Variables
-
 Variables are the way to store values we discussed earlier. In order to create a variable you can use a `let` keyword. Here is an example:
 
 ```ab
diff --git a/docs/by_example/bot_detector.md b/docs/by_example/bot_detector.md
@@ -1,5 +1,3 @@
-# Bot Detector
-
 This script is meant for periodic execution and must be run as root. It scans an Nginx webserver log file for large volumes of requests from automated bots not identifying themselves as bots. If a bad bot makes more than 1000 requests per hour then the IP address is added to a blocklist file that can be picked up by firewall block software such as ipset.
 
 ```ab
diff --git a/docs/by_example/examples.md b/docs/by_example/examples.md
@@ -1,5 +1,3 @@
-# Example Scripts
-
 > WARNING: Experimental standard library is used here. The full documentation covering it will be created soon as it get's more stable.
 
 Here, you’ll find a collection of practical scripts designed to help you quickly grasp the fundamentals and advanced features of the Amber programming language. Whether you are new to programming or an experienced developer, these examples will guide you through.
diff --git a/docs/by_example/lsp_installer.md b/docs/by_example/lsp_installer.md
@@ -1,8 +1,6 @@
-# LSP installer
-
 This script automates the installation of several Language Server Protocol (LSP) tools, primarily by downloading them from GitHub and installing them on your system. The latest version of the script (and also **complete**) can be found [here](https://github.com/Mte90/My-Scripts/blob/master/dev/lsp-installer/install.ab).
 
-> The script uses standard library functions to simplify the process of downloading, unpacking, and installing various LSP tools. It checks for necessary permissions, downloads the latest releases of selected LSPs, moves them to system directories, makes them executable, and installs additional LSPs using `npm`, `pip`, and `gem` as needed.  
+> The script uses standard library functions to simplify the process of downloading, unpacking, and installing various LSP tools. It checks for necessary permissions, downloads the latest releases of selected LSPs, moves them to system directories, makes them executable, and installs additional LSPs using `npm`, `pip`, and `gem` as needed.
 > For each tool, if the download or installation fails, an error message is displayed, and the script exits to prevent partial installations.
 
 ```ab
diff --git a/docs/by_example/sh_tester.md b/docs/by_example/sh_tester.md
@@ -1,8 +1,6 @@
-# ShellCheck tester
-
 This script is used within the project to automate the process of identifying any ShellCheck validation issues in our test cases after they are compiled to Bash scripts.
 
-> The script loops through all files in the Amber project's standard library test folder (`src/tests/stdlib/`), compiles each test to a Bash script, and then runs ShellCheck on the resulting script.  
+> The script loops through all files in the Amber project's standard library test folder (`src/tests/stdlib/`), compiles each test to a Bash script, and then runs ShellCheck on the resulting script.
 > If ShellCheck detects any issues (i.e., returns a non-zero exit code), the script generates a `.txt` report detailing the problems found. This report is stored in a designated temporary directory (`/tmp/amber-sc-tests`).
 
 ```ab
diff --git a/docs/by_example/ubuntu_updater.md b/docs/by_example/ubuntu_updater.md
@@ -1,5 +1,3 @@
-# Ubuntu Updater
-
 Here is an example script to periodically install software updates on an Ubuntu system. The update commands are wrapped in a `main` block, so that all commands between `$` signs can pass up errors with the `?` operator. The script will stop in that case and not execute any further commands.
 
 > As you can see, the Amber code currently looks as if it is intertwined with bash commands. As development progresses, executing custom commands will be even better integrated with special syntax and improved runtime safety features to aid this process.
diff --git a/docs/getting_started/getting_started.md b/docs/getting_started/getting_started.md
@@ -1,5 +1,3 @@
-# Getting started
-
 Welcome to the documentation of Amber the programming language! 🎉
 
 Here is a minimal hello world example:
@@ -28,4 +26,3 @@ Amber comes with a straightforward type system that aids in identifying simple b
 ### Extra features
 
 Amber supports things that are essential to developer like floating point arithmetic, a non-obscure way to handle arrays or even passing variables by reference instead of by copy. In addition to that Amber comes with a standard library that includes features like text trimming, summing all number in an array, splitting text and many more.
-
diff --git a/docs/getting_started/installation.md b/docs/getting_started/installation.md
@@ -1,5 +1,3 @@
-# Installation
-
 Amber compiler currently works on:
 - Linux x86 and ARM
 - macOS x86 and ARM (Apple Silicon)
diff --git a/docs/getting_started/usage.md b/docs/getting_started/usage.md
@@ -1,5 +1,3 @@
-# Usage
-
 Amber CLI can be used as a runtime or as a compiler.
 
 ## Command Line Interface (CLI) Parameters
diff --git a/docs/index.json b/docs/index.json
@@ -82,10 +82,6 @@
             "path": "stdlib/doc",
             "title": "Standard Library",
             "docs": [
-                {
-                    "path": "stdlib/doc",
-                    "title": "Documentation"
-                },
                 {
                     "path": "stdlib/doc/array",
                     "title": "Array"
diff --git a/src/app/[...slug]/page.module.css b/src/app/[...slug]/page.module.css
@@ -3,6 +3,12 @@
   width: 1000px;
 }
 
+.title {
+    font-weight: bold;
+    font-size: 2.5rem;
+    margin-bottom: 2rem;
+    vertical-align: middle;
+}
 
 .search {
   display: block;
@@ -18,7 +24,7 @@
 @media screen and (hover: none) {
   .no-hover {
     display: block;
-  } 
+  }
 }
 
 @media screen and (max-width: 1920px) {
@@ -38,4 +44,3 @@
     width: 80vw;
   }
 }
-
diff --git a/src/app/[...slug]/page.tsx b/src/app/[...slug]/page.tsx
@@ -17,11 +17,18 @@ interface Props {
   }
 }
 
+const getHeaders = (content: string) => {
+    let markdown = false
+    return content.split('\n').filter(line => {
+        if (line.startsWith('```')) markdown = !markdown
+        return !markdown && /^#+\s/.test(line)
+    })
+}
+
 const getDocument = async (path: string) => {
   const content = await getDoc(path)
   if (!content) return null
-  const rawHeaders = content.split('\n').filter(line => /^#+\s/.test(line))
-  const headers = rawHeaders.map(header => header.trim())
+  const headers = getHeaders(content)
   return { content, headers, path }
 }
 
@@ -46,6 +53,9 @@ export default async function Post({ params }: Props) {
               icon='/internal/swipe-to-copy.svg'
             />
           </div>
+          <div className={style.title}>
+            {docDesc.title}
+          </div>
           <Markdown content={doc.content} />
           <ChapterNavigation index={docDesc.index} />
         </div>
diff --git a/src/components/Markdown/Markdown.tsx b/src/components/Markdown/Markdown.tsx
@@ -14,7 +14,7 @@ hljs.registerAliases(['ab'], { languageName: 'amber' })
 // You can override the default renderer to customize the output
 class MarkdownRenderer extends Renderer {
     heading(text: string, level: number, raw: string): string {
-        const id = raw.toLowerCase().replace(/[^\w]+/g, '-')
+        const id = raw.toLowerCase().replace(/`([^`]+)`/g, '$1').replace(/[^\w]+/g, '-')
         return `
             <div class="${style.container}">
                 <div
diff --git a/src/components/SideBar/SideBar.tsx b/src/components/SideBar/SideBar.tsx
@@ -40,7 +40,7 @@ function getHeaders(headers: string[]): Header[] {
     let distances = [0, 0, 0]
     let prevLevel = NaN
     return headers.map(header => {
-        const level = getHeaderLevel(header) - 1
+        const level = Math.min(getHeaderLevel(header), 3) - 1
         const relation = getRelation(level, prevLevel)
         const distance = distances[level]
         for (const i of distances.keys()) {
@@ -50,7 +50,7 @@ function getHeaders(headers: string[]): Header[] {
         prevLevel = level
         return {
             level,
-            title: header.replace(/^#+\s/, ''),
+            title: header.replace(/^#+\s/, '').replaceAll(/`([^`]+)`/g, '$1'),
             relation,
             distance
         }
diff --git a/src/utils/docs.ts b/src/utils/docs.ts
@@ -19,4 +19,4 @@ export function getDocDescriptor(path: string) {
   const docs = Array.from(getFlatTableOfContents())
   const index = docs.findIndex((doc) => doc.path === path)
   return { index, ...docs[index] }
-}
+}

Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,3 @@`
`1`		`-# As cast`
`2`		`-`
`3`	`1`	As cast is a tool that might initially seem like an easy way to convert types. So, why has this functionality found its place in the advanced category? Well, with great power comes great responsibility. You could perform some casts that make sense, like from `Bool` to `Num`, but you could also perform casts that we refer to as _absurd_. An example of this might be converting `Text` to `Num`.
`4`	`2`
`5`	`3`	`## Regular casts`
Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,3 @@`
`1`		`-# Type condition`
`2`		`-`
`3`	`1`	`Sometimes when building generic functions one could find it very convenient to additionally validate if passed value is one of the data types that are supported.`
`4`	`2`
`5`	`3`	```ab
`@@ -9,4 +7,4 @@ fun getObject(value) {`
`9`	`7`	`value is Num: getById(value)`
`10`	`8`	`}`
`11`	`9`	`}`
`12`		-```
	`10`	+```
Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,3 @@`
`1`		`-# Arrays`
`2`		`-`
`3`	`1`	`We learned about array literals in the first chapter. In this chapter we will learn how to make use of them. Arrays are indexed from zero.`
`4`	`2`
`5`	`3`	`To store or retrieve a value at a particular index of an array, you can use the following syntax:`
Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,3 @@`
`1`		`-# Data types`
`2`		`-`
`3`	`1`	`Amber supports 5 data types:`
`4`	`2`	- `Text` - The textual data type. In other programming languages it can also be called "string".
`5`	`3`	- `Num` - The numeric data type. It's basically any number.