# Pen programming language
@@ -42,13 +42,13 @@ Pen aims to make large-scale software development efficient where many engineers
### Minimal language
-- Its [syntax][syntax] and [type system](/references/language/types.md) are small, simple, and easy to learn.
+- Its [syntax][syntax] and [type system](references/language/types.md) are small, simple, and easy to learn.
- Yet, the language supports all the modern features.
### Concurrent/parallel computation
- The language and its runtime enables thread-safe concurrent/parallel computation.
-- For more information, see [Concurrency and parallelism](/guides/concurrency-and-parallelism.md).
+- For more information, see [Concurrency and parallelism](guides/concurrency-and-parallelism.md).
### Reliable testing
@@ -75,13 +75,13 @@ Pen aims to make large-scale software development efficient where many engineers
- Pure functions by default
- [Errors as values][error-handling]
- Asynchronous I/O
-- [Cross compile](/advanced-features/cross-compile.md)
+- [Cross compile](advanced-features/cross-compile.md)
- [Rust](https://www.rust-lang.org/)/C Foreign Function Interface (FFI)
## License
Pen is dual-licensed under [MIT](https://github.com/pen-lang/pen/blob/main/LICENSE-MIT) and [Apache 2.0](https://github.com/pen-lang/pen/blob/main/LICENSE-APACHE).
-[error-handling]: /references/language/syntax.md#error-handling
-[syntax]: /references/language/syntax.md
-[system-packages]: /advanced-features/writing-system-packages.md
+[error-handling]: references/language/syntax.md#error-handling
+[syntax]: references/language/syntax.md
+[system-packages]: advanced-features/writing-system-packages.md
diff --git a/doc/src/advanced-features/cross-compile.md b/doc/docs/advanced-features/cross-compile.md
similarity index 65%
rename from doc/src/advanced-features/cross-compile.md
rename to doc/docs/advanced-features/cross-compile.md
index 6b29b0539b..47e7819739 100644
--- a/doc/src/advanced-features/cross-compile.md
+++ b/doc/docs/advanced-features/cross-compile.md
@@ -16,4 +16,4 @@ Run `pen build --help` to see all supported targets.
## System package support
-Cross compile support of [system packages](/references/language/packages.md#system-packages) are totally up to their developers. For example, [the `Os` standard system package](/references/standard-packages/os.md) supports most targets as long as their platforms expose OS-like APIs. However, some custom system packages might not support those targets because of their limited use cases.
+Cross compile support of [system packages](../references/language/packages.md#system-packages) are totally up to their developers. For example, [the `Os` standard system package](../references/standard-packages/os.md) supports most targets as long as their platforms expose OS-like APIs. However, some custom system packages might not support those targets because of their limited use cases.
diff --git a/doc/src/advanced-features/ffi.md b/doc/docs/advanced-features/ffi.md
similarity index 86%
rename from doc/src/advanced-features/ffi.md
rename to doc/docs/advanced-features/ffi.md
index 3882b36d33..252d52ba32 100644
--- a/doc/src/advanced-features/ffi.md
+++ b/doc/docs/advanced-features/ffi.md
@@ -4,7 +4,7 @@ Using FFI, you can import or export functions in foreign languages, such as [Rus
## Importing functions in foreign languages
-You can import functions in foreign languages using [foreign import statements](/references/language/syntax.md#foreign-import-statement). The statements specify the foreign functions' calling convention, names and types.
+You can import functions in foreign languages using [foreign import statements](../references/language/syntax.md#foreign-import-statement). The statements specify the foreign functions' calling convention, names and types.
You might specify calling conventions of foreign functions in a format of string literals after `import foreign` keywords optionally. Currently, only the C calling convention is supported as `"c"`. If the options are omitted, the functions are imported with the native calling convention of Pen.
@@ -16,7 +16,7 @@ import foreign "c" foo \(number, number) number
## Exporting functions to foreign languages
-You can export functions to foreign languages using [foreign function definitions](/references/language/syntax.md#foreign-function-definition), which have `foreign` keywords in front of normal function definitions.
+You can export functions to foreign languages using [foreign function definitions](../references/language/syntax.md#foreign-function-definition), which have `foreign` keywords in front of normal function definitions.
You might specify calling conventions of exported foreign functions optionally after `foreign` keywords as well as [imported foreign functions](#importing-functions-in-foreign-languages).
diff --git a/doc/src/advanced-features/writing-system-packages.md b/doc/docs/advanced-features/writing-system-packages.md
similarity index 97%
rename from doc/src/advanced-features/writing-system-packages.md
rename to doc/docs/advanced-features/writing-system-packages.md
index 3bac7611bd..d7e51198bb 100644
--- a/doc/src/advanced-features/writing-system-packages.md
+++ b/doc/docs/advanced-features/writing-system-packages.md
@@ -5,7 +5,7 @@ Using existing system packages covers most use cases in application development.
- Define your own system interfaces of functions and types with side effects.
- Link applications in arbitrary file formats.
-This page assumes that you have already read [Packages](/references/language/packages.md).
+This page assumes that you have already read [Packages](../references/language/packages.md).
> Caveat: Providing bad system packages which do not conform to conventions can break the ecosystem of the language! In the worst cases, they might make applications malfunction. Please be careful to follow the conventions to keep applications maintainable and portable.
diff --git a/doc/src/examples/.gitignore b/doc/docs/examples/.gitignore
similarity index 100%
rename from doc/src/examples/.gitignore
rename to doc/docs/examples/.gitignore
diff --git a/doc/src/guides/building-an-executable.md b/doc/docs/guides/building-an-executable.md
similarity index 80%
rename from doc/src/guides/building-an-executable.md
rename to doc/docs/guides/building-an-executable.md
index 6763c538d3..711798608c 100644
--- a/doc/src/guides/building-an-executable.md
+++ b/doc/docs/guides/building-an-executable.md
@@ -7,14 +7,14 @@ This page describes how to build an executable of a program written in Pen. It c
## Creating an application package
-[Application packages](/references/language/packages.md#application-packages) are packages that are built into executables.
+[Application packages](../references/language/packages.md#application-packages) are packages that are built into executables.
To create it, you run a `pen create` command with your application's name (e.g. `foo`) in your terminal.
```sh
pen create foo
```
-Then, you should see a `foo` directory in your current directory. When you go there, you should see a `main.pen` source file and a `pen.json` file for [package configuration](/references/language/packages.md#package-configuration).
+Then, you should see a `foo` directory in your current directory. When you go there, you should see a `main.pen` source file and a `pen.json` file for [package configuration](../references/language/packages.md#package-configuration).
`main.pen`:
@@ -39,7 +39,7 @@ main = \(ctx context) none {
}
```
-In this example, the `main.pen` file contains a program that outputs a text, "Hello, world!" in a terminal. And the `pen.json` configuration file defines a package type of `application` and its dependencies. Here, it has only a dependency of the `Os` [system package](/references/language/packages.md#system-packages).
+In this example, the `main.pen` file contains a program that outputs a text, "Hello, world!" in a terminal. And the `pen.json` configuration file defines a package type of `application` and its dependencies. Here, it has only a dependency of the `Os` [system package](../references/language/packages.md#system-packages).
## Building a package into an executable
@@ -59,4 +59,4 @@ Then, you will see an executable file named `app` in the directory. Now, you can
- [Creating a library](creating-a-library.md)
- [Using a library](using-a-library.md)
-- [Language syntax](/references/language/syntax.md)
+- [Language syntax](../references/language/syntax.md)
diff --git a/doc/src/guides/coding-style.md b/doc/docs/guides/coding-style.md
similarity index 100%
rename from doc/src/guides/coding-style.md
rename to doc/docs/guides/coding-style.md
diff --git a/doc/src/guides/concurrency-and-parallelism.md b/doc/docs/guides/concurrency-and-parallelism.md
similarity index 91%
rename from doc/src/guides/concurrency-and-parallelism.md
rename to doc/docs/guides/concurrency-and-parallelism.md
index 4e808a591e..17cb3bb83b 100644
--- a/doc/src/guides/concurrency-and-parallelism.md
+++ b/doc/docs/guides/concurrency-and-parallelism.md
@@ -10,7 +10,7 @@ Pen provides several built-in functions for concurrent and parallel programming.
### `go` function
-[The `go` built-in function](/references/language/built-ins.html#go) runs a given function concurrently, and possibly in parallel.
+[The `go` built-in function](../references/language/built-ins.md#go) runs a given function concurrently, and possibly in parallel.
```pen
future = go(\() number {
@@ -20,11 +20,11 @@ future = go(\() number {
The `go` function returns a function of the same type as the given argument. The returned function returns a resulting value of the function execution. In other languages, such functions returning values computed concurrently when they are ready are also known as [futures](https://doc.rust-lang.org/std/future/trait.Future.html) or [promises](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise).
-The `go` function may or may not run a given function immediately depending on its implementation. For example, [the standard `Os` system package](/references/standard-packages/os.md) runs the given function in parallel if multiple CPU cores are available.
+The `go` function may or may not run a given function immediately depending on its implementation. For example, [the standard `Os` system package](../references/standard-packages/os.md) runs the given function in parallel if multiple CPU cores are available.
### `race` function
-[The `race` built-in function](/references/language/built-ins.html#race) takes multiple lists and merge them into one by evaluating elements in each list concurrently and possibly in parallel. The resulting list contains the elements in the original lists in order of their finished times of computation. Remember that elements in lists are evaluated lazily.
+[The `race` built-in function](../references/language/built-ins.md#race) takes multiple lists and merge them into one by evaluating elements in each list concurrently and possibly in parallel. The resulting list contains the elements in the original lists in order of their finished times of computation. Remember that elements in lists are evaluated lazily.
```pen
zs = race([[number] xs, ys])
diff --git a/doc/src/guides/creating-a-library.md b/doc/docs/guides/creating-a-library.md
similarity index 81%
rename from doc/src/guides/creating-a-library.md
rename to doc/docs/guides/creating-a-library.md
index 668ff9aca2..54d47f5497 100644
--- a/doc/src/guides/creating-a-library.md
+++ b/doc/docs/guides/creating-a-library.md
@@ -7,14 +7,14 @@ This page describes how to create a library in Pen. It consists of the following
## Creating a library package
-[Library packages](/references/language/packages.md#library-packages) are packages imported and used by other packages.
+[Library packages](../references/language/packages.md#library-packages) are packages imported and used by other packages.
To create it, you run a `pen create --library` command with your library's name (e.g. `foo`) in your terminal.
```sh
pen create --library foo
```
-Then, you should see a `foo` directory in your current directory. When you go there, you should see a `Foo.pen` source file and a `pen.json` file for [package configuration](/references/language/packages.md#package-configuration).
+Then, you should see a `foo` directory in your current directory. When you go there, you should see a `Foo.pen` source file and a `pen.json` file for [package configuration](../references/language/packages.md#package-configuration).
`Foo.pen`:
@@ -52,4 +52,4 @@ Now, your package is ready for use by other packages!
- [Building an executable](building-an-executable.md)
- [Using a library](using-a-library.md)
-- [Language syntax](/references/language/syntax.md)
+- [Language syntax](../references/language/syntax.md)
diff --git a/doc/src/guides/testing.md b/doc/docs/guides/testing.md
similarity index 89%
rename from doc/src/guides/testing.md
rename to doc/docs/guides/testing.md
index ec446d5035..97464d5e1d 100644
--- a/doc/src/guides/testing.md
+++ b/doc/docs/guides/testing.md
@@ -24,7 +24,7 @@ CheckFoo = \() none | error {
### The `Test` package
-[The `Test` standard package](/references/standard-packages/test.md) includes some utilities which helps you to write tests.
+[The `Test` standard package](../references/standard-packages/test.md) includes some utilities which helps you to write tests.
## Running tests
diff --git a/doc/src/guides/using-a-library.md b/doc/docs/guides/using-a-library.md
similarity index 87%
rename from doc/src/guides/using-a-library.md
rename to doc/docs/guides/using-a-library.md
index 15b8418bdd..e83f9dd63e 100644
--- a/doc/src/guides/using-a-library.md
+++ b/doc/docs/guides/using-a-library.md
@@ -7,7 +7,7 @@ This page describes how to use a library in Pen. It consists of the following st
## Modifying package configuration
-To use a library package, you need to add the package as a dependency in another package. To add the dependency, you modify a `pen.json` configuration file in the package adding the library package's name (e.g. `Foo`) and URL (e.g. `git://github.com/your-name/foo`) in a `dependencies` field like the following example. Note that you need to specify a `git` protocol scheme for library packages published as Git repositories. For other kinds of library packages, see [Package configuration](/references/language/packages.md#package-configuration).
+To use a library package, you need to add the package as a dependency in another package. To add the dependency, you modify a `pen.json` configuration file in the package adding the library package's name (e.g. `Foo`) and URL (e.g. `git://github.com/your-name/foo`) in a `dependencies` field like the following example. Note that you need to specify a `git` protocol scheme for library packages published as Git repositories. For other kinds of library packages, see [Package configuration](../references/language/packages.md#package-configuration).
```json
{
@@ -40,5 +40,5 @@ MyFunction = \(x number, y number) number {
- [Building an executable](building-an-executable.md)
- [Creating a library](creating-a-library.md)
-- [Language syntax](/references/language/syntax.md)
- - [Import statement](/references/language/syntax.md#import-statement)
+- [Language syntax](../references/language/syntax.md)
+ - [Import statement](../references/language/syntax.md#import-statement)
diff --git a/doc/src/introduction/getting-started.md b/doc/docs/introduction/building-the-first-program.md
similarity index 55%
rename from doc/src/introduction/getting-started.md
rename to doc/docs/introduction/building-the-first-program.md
index 45534b5b2b..b47194dad9 100644
--- a/doc/src/introduction/getting-started.md
+++ b/doc/docs/introduction/building-the-first-program.md
@@ -1,8 +1,4 @@
-# Getting started
-
-## Install
-
-See [Install](install.md).
+# Building the first program
## Creating a package
@@ -12,7 +8,7 @@ To create your first package, run a `pen create` command with your package's nam
pen create foo
```
-Then, you should see a directory named `foo` in your current directory. When you go into the directory, you should see a `main.pen` source file and a `pen.json` file for [package configuration](/references/language/packages.md#package-configuration).
+Then, you should see a directory named `foo` in your current directory. When you go into the directory, you should see a `main.pen` source file and a `pen.json` file for [package configuration](../references/language/packages.md#package-configuration).
## Building a package
@@ -32,8 +28,8 @@ Now, you can start editing source files and build your own application in Pen!
## Next steps
-- To use other library packages, see [Using a library](/guides/using-a-library.md).
-- For more code examples, see [Examples](/examples).
-- For the language syntax, see [Syntax](/references/language/syntax.md) and [Types](/references/language/types.md).
-- For usage of the standard packages, see [Standard packages](/references/standard-packages).
-- To add more modules in your package, see [Modules](/references/language/modules.md).
+- To use other library packages, see [Using a library](../guides/using-a-library.md).
+- For more code examples, see [Examples](../examples/types/number.md).
+- For the language syntax, see [Syntax](../references/language/syntax.md) and [Types](../references/language/types.md).
+- For usage of the standard packages, see [Standard packages](../references/standard-packages/core.md).
+- To add more modules in your package, see [Modules](../references/language/modules.md).
diff --git a/doc/src/introduction/install.md b/doc/docs/introduction/install.md
similarity index 100%
rename from doc/src/introduction/install.md
rename to doc/docs/introduction/install.md
diff --git a/doc/src/references/command-line-tools.md b/doc/docs/references/command-line-tools.md
similarity index 100%
rename from doc/src/references/command-line-tools.md
rename to doc/docs/references/command-line-tools.md
diff --git a/doc/src/references/language/built-ins.md b/doc/docs/references/language/built-ins.md
similarity index 100%
rename from doc/src/references/language/built-ins.md
rename to doc/docs/references/language/built-ins.md
diff --git a/doc/src/references/language/modules.md b/doc/docs/references/language/modules.md
similarity index 85%
rename from doc/src/references/language/modules.md
rename to doc/docs/references/language/modules.md
index 351236b11c..560f1a6e58 100644
--- a/doc/src/references/language/modules.md
+++ b/doc/docs/references/language/modules.md
@@ -22,7 +22,7 @@ Foo = \() number {
## Importing functions and types from modules
-In order to import functions and types from other modules, place [import statements](/references/language/syntax.md#import-statement) at the top of modules.
+In order to import functions and types from other modules, place [import statements](syntax.md#import-statement) at the top of modules.
The first components in the statements are names of external packages you declare in [package configuration files][package-configuration] (`Foo`.) They are omitted if imported modules are in the same packages. The rest of the components are directory names where the modules exist (`Bar`) and the modules' filenames without their file extensions (`Baz` for `Baz.pen`.)
@@ -74,11 +74,9 @@ Imported modules can have custom prefixes given different names after the `as` k
import Foo'Bar'Baz as Blah
```
-[package-configuration]: packages.md#package-configuration
-
### Unqualified import
-You can import functions and types without prefixes by putting their names between `{` and `}` in [import statements](/references/language/syntax.md#import-statement). This is especially useful when module names and imported functions or types have the same names like `import 'MyType { MyType }`.
+You can import functions and types without prefixes by putting their names between `{` and `}` in [import statements](syntax.md#import-statement). This is especially useful when module names and imported functions or types have the same names like `import 'MyType { MyType }`.
```pen
import Foo'Bar { Foo, Bar }
diff --git a/doc/src/references/language/packages.md b/doc/docs/references/language/packages.md
similarity index 91%
rename from doc/src/references/language/packages.md
rename to doc/docs/references/language/packages.md
index d4871d0598..adef316e04 100644
--- a/doc/src/references/language/packages.md
+++ b/doc/docs/references/language/packages.md
@@ -1,12 +1,12 @@
# Packages
-Packages are sets of [modules](/references/language/modules.md). Like modules, packages can import other packages specifying them in [their configurations](#package-configuration).
+Packages are sets of [modules](modules.md). Like modules, packages can import other packages specifying them in [their configurations](#package-configuration).
## What composes a package?
The following entities compose packages.
-- Standard packages bundled in [installation](/introduction/install.md) of the language
+- Standard packages bundled in [installation](../../introduction/install.md) of the language
- Remote repositories managed by version control systems (VCS)
- Currently, Pen supports only [Git](https://git-scm.com/) as a VCS.
- Directories with [package configuration files](#package-configuration) on file systems
@@ -42,7 +42,7 @@ System packages contain functions and types that have side effects to provide sy
Although they can be imported by library packages as well as application packages, then they are expected not to cause any side effects.
-If you want to write your own system packages, see [Writing system packages](/advanced-features/writing-system-packages.md).
+If you want to write your own system packages, see [Writing system packages](../../advanced-features/writing-system-packages.md).
## Package configuration
diff --git a/doc/src/references/language/syntax.md b/doc/docs/references/language/syntax.md
similarity index 96%
rename from doc/src/references/language/syntax.md
rename to doc/docs/references/language/syntax.md
index 1c88cd7fcc..15314032ee 100644
--- a/doc/src/references/language/syntax.md
+++ b/doc/docs/references/language/syntax.md
@@ -24,7 +24,7 @@ import Foo'Bar
It imports a function from a foreign language.
-See [Foreign Function Interface (FFI)](/advanced-features/ffi.md) for more details.
+See [Foreign Function Interface (FFI)](../../advanced-features/ffi.md) for more details.
```pen
import foreign "c" foo \(number, number) number
@@ -65,7 +65,7 @@ foo = \(x number, y number) number {
It defines a function exported to foreign languages.
-See [Foreign Function Interface (FFI)](/advanced-features/ffi.md) for more details.
+See [Foreign Function Interface (FFI)](../../advanced-features/ffi.md) for more details.
```pen
foreign "c" foo = \(x number, y number) number {
diff --git a/doc/src/references/language/types.md b/doc/docs/references/language/types.md
similarity index 100%
rename from doc/src/references/language/types.md
rename to doc/docs/references/language/types.md
diff --git a/doc/src/references/standard-packages/.gitignore b/doc/docs/references/standard-packages/.gitignore
similarity index 100%
rename from doc/src/references/standard-packages/.gitignore
rename to doc/docs/references/standard-packages/.gitignore
diff --git a/doc/src/roadmap.md b/doc/docs/roadmap.md
similarity index 100%
rename from doc/src/roadmap.md
rename to doc/docs/roadmap.md
diff --git a/doc/src/the-zen.md b/doc/docs/the-zen.md
similarity index 63%
rename from doc/src/the-zen.md
rename to doc/docs/the-zen.md
index e793d14d4f..3765cce07d 100644
--- a/doc/src/the-zen.md
+++ b/doc/docs/the-zen.md
@@ -1,22 +1,14 @@
# The Zen
-- Beautiful is better than ugly.
-- Explicit is better than implicit.
- Simple is better than complex.
+- Explicit is better than implicit.
+- Clear is better than clever.
- One way to do one thing
-- Single solution for multiple problems
+- One solution for many problems
- Steady value over volatile value
-## Language qualities
-
-In the order of priority,
-
-- Simplicity
-- Readability
-- Consistency
-- Writability
-
## References
+- [Go Proverbs](https://go-proverbs.github.io/)
- [The Zen of Python](https://www.python.org/dev/peps/pep-0020/)
- [Zen | The Zig programming language](https://ziglang.org/documentation/master/#Zen)
diff --git a/doc/mkdocs.yaml b/doc/mkdocs.yaml
new file mode 100644
index 0000000000..421188210c
--- /dev/null
+++ b/doc/mkdocs.yaml
@@ -0,0 +1,100 @@
+site_name: Pen programming language
+site_description: The programming language for scalable development
+site_url: https://pen-lang.org/
+repo_url: https://github.com/pen-lang/pen
+edit_uri: edit/main/docs/
+strict: true
+theme:
+ name: material
+ custom_dir: theme
+ features:
+ - navigation.tabs
+ favicon: icon.svg
+ logo: icon.svg
+ palette:
+ - scheme: default
+ primary: black
+ accent: red
+ toggle:
+ icon: material/brightness-7
+ name: Switch to dark mode
+ - scheme: slate
+ primary: black
+ accent: red
+ toggle:
+ icon: material/brightness-4
+ name: Switch to light mode
+markdown_extensions:
+ - mdx_truly_sane_lists
+ - pymdownx.tasklist:
+ custom_checkbox: true
+nav:
+ - Home:
+ - Overview: README.md
+ - roadmap.md
+ - the-zen.md
+ - Getting started:
+ - introduction/install.md
+ - introduction/building-the-first-program.md
+ - Guides:
+ - guides/building-an-executable.md
+ - guides/creating-a-library.md
+ - guides/using-a-library.md
+ - guides/testing.md
+ - guides/concurrency-and-parallelism.md
+ - guides/coding-style.md
+ - Advanced features:
+ - advanced-features/cross-compile.md
+ - advanced-features/ffi.md
+ - advanced-features/writing-system-packages.md
+ - References:
+ - Language:
+ - references/language/syntax.md
+ - references/language/types.md
+ - references/language/built-ins.md
+ - references/language/modules.md
+ - references/language/packages.md
+ - references/command-line-tools.md
+ - Standard packages:
+ - Core: references/standard-packages/core.md
+ - Flag: references/standard-packages/flag.md
+ - Json: references/standard-packages/json.md
+ - Html: references/standard-packages/html.md
+ - Http: references/standard-packages/http.md
+ - Os: references/standard-packages/os.md
+ - Random: references/standard-packages/random.md
+ - Regex: references/standard-packages/regex.md
+ - Sql: references/standard-packages/sql.md
+ - Test: references/standard-packages/test.md
+ - Examples:
+ - Types:
+ - examples/types/number.md
+ - examples/types/boolean.md
+ - examples/types/none.md
+ - examples/types/string.md
+ - examples/types/function.md
+ - examples/types/record.md
+ - examples/types/union.md
+ - examples/types/list.md
+ - examples/types/map.md
+ - examples/types/error.md
+ - examples/types/any.md
+ - examples/types/polymorphism.md
+ - examples/types/stream.md
+ - Syntax:
+ - examples/syntax/block.md
+ - examples/syntax/concurrency.md
+ - Modules: examples/module.md
+ - Packages: examples/package.md
+ - Commands:
+ - examples/commands/build.md
+ - examples/commands/create.md
+ - examples/commands/test.md
+ - examples/commands/format.md
+ - examples/commands/document.md
+ - Standard packages:
+ - examples/standard-packages/core.md
+ - examples/standard-packages/os.md
+ - examples/standard-packages/random.md
+ - examples/standard-packages/test.md
+ - examples/ffi.md
diff --git a/doc/package-lock.json b/doc/package-lock.json
new file mode 100644
index 0000000000..fed137d943
--- /dev/null
+++ b/doc/package-lock.json
@@ -0,0 +1,27 @@
+{
+ "name": "doc",
+ "lockfileVersion": 2,
+ "requires": true,
+ "packages": {
+ "": {
+ "dependencies": {
+ "@highlightjs/cdn-assets": "^11.6.0"
+ }
+ },
+ "node_modules/@highlightjs/cdn-assets": {
+ "version": "11.6.0",
+ "resolved": "https://registry.npmjs.org/@highlightjs/cdn-assets/-/cdn-assets-11.6.0.tgz",
+ "integrity": "sha512-Mod+0LGTetSd0JbLGOHesCP3FLz8T/BOuDitF6stBNmHSLDmds1i4hT02T98Xlj3bGgPCbRsiF2D7i0Nraa+sQ==",
+ "engines": {
+ "node": ">=12.0.0"
+ }
+ }
+ },
+ "dependencies": {
+ "@highlightjs/cdn-assets": {
+ "version": "11.6.0",
+ "resolved": "https://registry.npmjs.org/@highlightjs/cdn-assets/-/cdn-assets-11.6.0.tgz",
+ "integrity": "sha512-Mod+0LGTetSd0JbLGOHesCP3FLz8T/BOuDitF6stBNmHSLDmds1i4hT02T98Xlj3bGgPCbRsiF2D7i0Nraa+sQ=="
+ }
+ }
+}
diff --git a/doc/package.json b/doc/package.json
new file mode 100644
index 0000000000..171776982a
--- /dev/null
+++ b/doc/package.json
@@ -0,0 +1,8 @@
+{
+ "scripts": {
+ "build": "rm -rf theme/assets && mkdir -p theme/assets && cp -r node_modules/@highlightjs/cdn-assets theme/assets/highlight"
+ },
+ "dependencies": {
+ "@highlightjs/cdn-assets": "^11.6.0"
+ }
+}
diff --git a/doc/requirements.txt b/doc/requirements.txt
new file mode 100644
index 0000000000..7993b981b0
--- /dev/null
+++ b/doc/requirements.txt
@@ -0,0 +1,3 @@
+mdx-truly-sane-lists==1.3
+mkdocs==1.3.1
+mkdocs-material==8.4.2
diff --git a/doc/src/SUMMARY.md b/doc/src/SUMMARY.md
deleted file mode 100644
index f06dbe3260..0000000000
--- a/doc/src/SUMMARY.md
+++ /dev/null
@@ -1,65 +0,0 @@
-# Summary
-
-- [Introduction](README.md)
- - [Install](introduction/install.md)
- - [Getting started](introduction/getting-started.md)
-- [Guides](guides/README.md)
- - [Building an executable](guides/building-an-executable.md)
- - [Creating a library](guides/creating-a-library.md)
- - [Using a library](guides/using-a-library.md)
- - [Testing](guides/testing.md)
- - [Concurrency and parallelism](guides/concurrency-and-parallelism.md)
- - [Coding style](guides/coding-style.md)
-- [References](references/README.md)
- - [Language](references/language/README.md)
- - [Syntax](references/language/syntax.md)
- - [Types](references/language/types.md)
- - [Built-ins](references/language/built-ins.md)
- - [Modules](references/language/modules.md)
- - [Packages](references/language/packages.md)
- - [Command line tools](references/command-line-tools.md)
- - [Standard packages](references/standard-packages/README.md)
- - [`Core`](references/standard-packages/core.md)
- - [`Flag`](references/standard-packages/flag.md)
- - [`Json`](references/standard-packages/json.md)
- - [`Html`](references/standard-packages/html.md)
- - [`Http`](references/standard-packages/http.md)
- - [`Os`](references/standard-packages/os.md)
- - [`Random`](references/standard-packages/random.md)
- - [`Regex`](references/standard-packages/regex.md)
- - [`Sql`](references/standard-packages/sql.md)
- - [`Test`](references/standard-packages/test.md)
-- [Examples](examples/README.md)
- - [Types](examples/types/README.md)
- - [Number](examples/types/number.md)
- - [Boolean](examples/types/boolean.md)
- - [None](examples/types/none.md)
- - [String](examples/types/string.md)
- - [Function](examples/types/function.md)
- - [Record](examples/types/record.md)
- - [Union](examples/types/union.md)
- - [List](examples/types/list.md)
- - [Error](examples/types/error.md)
- - [Any](examples/types/any.md)
- - [Polymorphism](examples/types/polymorphism.md)
- - [Syntax](examples/syntax/README.md)
- - [Block](examples/syntax/block.md)
- - [Modules](examples/module.md)
- - [Packages](examples/package.md)
- - [Commands](examples/commands/README.md)
- - [Building packages](examples/commands/build.md)
- - [Creating packages](examples/commands/create.md)
- - [Testing packages](examples/commands/test.md)
- - [Formatting module files](examples/commands/format.md)
- - [Standard packages](examples/standard-packages/README.md)
- - [`Core`](examples/standard-packages/core.md)
- - [`Os`](examples/standard-packages/os.md)
- - [`Random`](examples/standard-packages/random.md)
- - [`Test`](examples/standard-packages/test.md)
- - [Foreign Function Interface (FFI)](examples/ffi.md)
-- [Advanced features](advanced-features/README.md)
- - [Cross compile](advanced-features/cross-compile.md)
- - [Foreign Function Interface (FFI)](advanced-features/ffi.md)
- - [Writing system packages](advanced-features/writing-system-packages.md)
-- [Roadmap](roadmap.md)
-- [The Zen](the-zen.md)
diff --git a/doc/src/advanced-features/README.md b/doc/src/advanced-features/README.md
deleted file mode 100644
index 610b048831..0000000000
--- a/doc/src/advanced-features/README.md
+++ /dev/null
@@ -1,3 +0,0 @@
-# Advanced features
-
-This chapter lists advanced features of Pen and describe when and how to use them.
diff --git a/doc/src/examples/README.md b/doc/src/examples/README.md
deleted file mode 100644
index 058628e1a2..0000000000
--- a/doc/src/examples/README.md
+++ /dev/null
@@ -1,5 +0,0 @@
-# Examples
-
-These are examples on how to write programs in Pen, and use its command line tools and standard packages.
-
-See also [our code repository](https://github.com/pen-lang/pen/tree/main/examples) for examples of full applications and libraries.
diff --git a/doc/src/examples/commands/README.md b/doc/src/examples/commands/README.md
deleted file mode 100644
index fe35b51e24..0000000000
--- a/doc/src/examples/commands/README.md
+++ /dev/null
@@ -1,3 +0,0 @@
-# Commands
-
-These are examples on how to use command line tools of Pen.
diff --git a/doc/src/examples/standard-packages/README.md b/doc/src/examples/standard-packages/README.md
deleted file mode 100644
index 12c1d81b4b..0000000000
--- a/doc/src/examples/standard-packages/README.md
+++ /dev/null
@@ -1,3 +0,0 @@
-# Standard packages
-
-These are examples on how to use standard packages.
diff --git a/doc/src/examples/syntax/README.md b/doc/src/examples/syntax/README.md
deleted file mode 100644
index bae4f1d836..0000000000
--- a/doc/src/examples/syntax/README.md
+++ /dev/null
@@ -1,3 +0,0 @@
-# Syntax
-
-These are examples on how to write programs in Pen.
diff --git a/doc/src/examples/types/README.md b/doc/src/examples/types/README.md
deleted file mode 100644
index 12ae94065e..0000000000
--- a/doc/src/examples/types/README.md
+++ /dev/null
@@ -1,3 +0,0 @@
-# Types
-
-These are examples on how to use types and their values in Pen.
diff --git a/doc/src/guides/README.md b/doc/src/guides/README.md
deleted file mode 100644
index d34761a42f..0000000000
--- a/doc/src/guides/README.md
+++ /dev/null
@@ -1,3 +0,0 @@
-# Guides
-
-This chapter contains how-to guides for software development in Pen.
diff --git a/doc/src/references/README.md b/doc/src/references/README.md
deleted file mode 100644
index 3f295dbe88..0000000000
--- a/doc/src/references/README.md
+++ /dev/null
@@ -1,3 +0,0 @@
-# References
-
-This chapter details language features, command line tools, and standard packages.
diff --git a/doc/src/references/language/README.md b/doc/src/references/language/README.md
deleted file mode 100644
index 9859e60e6b..0000000000
--- a/doc/src/references/language/README.md
+++ /dev/null
@@ -1,3 +0,0 @@
-# Language
-
-This chapter describes the Pen's syntax, and type, module and package systems.
diff --git a/doc/src/references/standard-packages/README.md b/doc/src/references/standard-packages/README.md
deleted file mode 100644
index ee330c21d8..0000000000
--- a/doc/src/references/standard-packages/README.md
+++ /dev/null
@@ -1,3 +0,0 @@
-# Standard packages
-
-Standard packages provide common utility functions and system interfaces. They are installed together with the `pen` command on your system. This chapter describes their APIs and how to use them.
diff --git a/doc/theme/custom-highlight.js b/doc/theme/custom-highlight.js
deleted file mode 100644
index 04a2b340ce..0000000000
--- a/doc/theme/custom-highlight.js
+++ /dev/null
@@ -1,21 +0,0 @@
-hljs.registerLanguage("pen", (hljs) => ({
- name: "Pen",
- keywords: {
- keyword: "as else for foreign go if import in type",
- built_in: "any boolean error none number string",
- literal: "false none true",
- },
- contains: [
- hljs.QUOTE_STRING_MODE,
- hljs.C_NUMBER_MODE,
- {
- scope: "string",
- begin: '"',
- end: '"',
- contains: [{ begin: "\\\\." }],
- },
- hljs.COMMENT("#", "$"),
- ],
-}));
-
-hljs.initHighlightingOnLoad();
diff --git a/doc/theme/head.hbs b/doc/theme/head.hbs
deleted file mode 100644
index 63f34e4312..0000000000
--- a/doc/theme/head.hbs
+++ /dev/null
@@ -1,8 +0,0 @@
-
-
diff --git a/doc/theme/main.html b/doc/theme/main.html
new file mode 100644
index 0000000000..45be7a71d0
--- /dev/null
+++ b/doc/theme/main.html
@@ -0,0 +1,46 @@
+{% extends "base.html" %} {% block extrahead %}
+
+
+
+
+{% endblock %}
diff --git a/tools/ci/github/setup.sh b/tools/ci/github/setup.sh
index c095b2d6ba..49ba6079ef 100755
--- a/tools/ci/github/setup.sh
+++ b/tools/ci/github/setup.sh
@@ -5,7 +5,7 @@ set -e
llvm_version=14
brew update
-brew install jq llvm@$llvm_version mdbook ninja sccache
+brew install jq llvm@$llvm_version ninja sccache
llvm_prefix=$(brew --prefix)/opt/llvm@$llvm_version
diff --git a/tools/build_documents.sh b/tools/document/build.sh
similarity index 82%
rename from tools/build_documents.sh
rename to tools/document/build.sh
index 806a45efbe..7222a3b128 100755
--- a/tools/build_documents.sh
+++ b/tools/document/build.sh
@@ -2,7 +2,7 @@
set -ex
-document_directory=doc/src/references/standard-packages
+document_directory=doc/docs/references/standard-packages
build_package_document() {
(
@@ -14,7 +14,7 @@ build_package_document() {
) >$document_directory/$1.md
}
-cd $(dirname $0)/..
+cd $(dirname $0)/../..
tools/build.sh
@@ -70,12 +70,17 @@ build_package_document \
Test \
"This package provides test utilities."
-go run github.com/raviqqe/gherkin2markdown features doc/src/examples
+go run github.com/raviqqe/gherkin2markdown features doc/docs/examples
-curl -fsSL https://pen-lang.s3.us-west-1.amazonaws.com/icon.svg >doc/src/favicon.svg
+curl -fsSL https://pen-lang.s3.us-west-1.amazonaws.com/icon.svg >doc/docs/icon.svg
-# spell-checker: disable-next-line
-cargo install mdbook-pagetoc
+(
+ cd doc
-cd doc
-mdbook build
+ npm install
+ npm run build
+
+ pip3 install -r requirements.txt
+
+ mkdocs build
+)
diff --git a/tools/document/serve.sh b/tools/document/serve.sh
new file mode 100755
index 0000000000..7a4eb9e4b0
--- /dev/null
+++ b/tools/document/serve.sh
@@ -0,0 +1,8 @@
+#!/bin/sh
+
+set -e
+
+$(dirname $0)/build.sh
+
+cd doc
+mkdocs serve
diff --git a/tools/serve_documents.sh b/tools/serve_documents.sh
deleted file mode 100755
index 479aada9e2..0000000000
--- a/tools/serve_documents.sh
+++ /dev/null
@@ -1,10 +0,0 @@
-#!/bin/sh
-
-set -e
-
-$(dirname $0)/build_documents.sh
-
-(
- cd $(dirname $0)/../doc
- mdbook serve "$@"
-)
