Update documentation (#1410)

.cspell.json

@@ -38,7 +38,7 @@
     "lcov",
     "libc",
     "malloc",
-    "mdbook",
+    "mkdocs",
     "modifiability",
     "mtriple",
     "optarg",

.github/dependabot.yml

@@ -16,3 +16,11 @@ updates:
     directory: /
     schedule:
       interval: daily
+  - package-ecosystem: npm
+    directory: /doc
+    schedule:
+      interval: daily
+  - package-ecosystem: pip
+    directory: /doc
+    schedule:
+      interval: daily

.github/workflows/documentation.yaml

@@ -10,9 +10,9 @@ jobs:
     steps:
       - uses: actions/checkout@main
       - run: tools/ci/github/setup.sh
-      - run: tools/build_documents.sh
+      - run: tools/document/build.sh
       - uses: peaceiris/actions-gh-pages@v3
         if: github.ref == 'refs/heads/main'
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: doc/book
+          publish_dir: doc/site

.gitignore

@@ -5,6 +5,8 @@
 *.svg
 *.tar.*
 .pen
+assets
 dhat-*
+site
 target
 tmp

doc/docs/CNAME

@@ -0,0 +1 @@
+pen-lang.org

doc/src/README.md → doc/docs/README.md

@@ -1,4 +1,4 @@
-<p align="center"><img width="300px" src="/favicon.svg" /></p>
+<p align="center"><img width="300px" src="icon.svg" /></p>
 
 # 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

doc/src/advanced-features/cross-compile.md → 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.

doc/src/advanced-features/ffi.md → 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).
 

doc/src/advanced-features/writing-system-packages.md → 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.
 

doc/src/guides/building-an-executable.md → 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)

doc/src/guides/concurrency-and-parallelism.md → 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])

doc/src/guides/creating-a-library.md → 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)

doc/src/guides/testing.md → 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
 

doc/src/guides/using-a-library.md → 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)

doc/src/introduction/getting-started.md → 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).

doc/src/references/language/modules.md → 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 }

doc/src/references/language/packages.md → 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
 

doc/src/references/language/syntax.md → 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 {

doc/src/the-zen.md → 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)