🚧 Start writing documentation

ortfo · Apr 14, 2024 · 8226e1d · 8226e1d
1 parent 5d8ccec
commit 8226e1d
Show file tree

Hide file tree

Showing 39 changed files with 388 additions and 155 deletions.
diff --git a/.editorconfig b/.editorconfig
@@ -0,0 +1,2 @@
+[*.md]
+indent_style = space
diff --git a/.vitepress/config.mts b/.vitepress/config.mts
@@ -1,10 +1,16 @@
 import { defineConfig } from "vitepress"
+import footnote from "markdown-it-footnote"
 
 // https://vitepress.dev/reference/site-config
 export default defineConfig({
   lang: "en-US",
   title: "ortfo",
   description: "Make & manage your own homemade portfolio easily",
+  markdown: {
+    config: (md) => {
+      md.use(footnote)
+    },
+  },
   themeConfig: {
     search: {
       provider: "local",
@@ -13,18 +19,97 @@ export default defineConfig({
     // https://vitepress.dev/reference/default-theme-config
     nav: [
       { text: "Home", link: "/" },
-      { text: "Examples", link: "/markdown-examples" },
+      { text: "ortfo/db", link: "/db/" },
     ],
 
-    sidebar: [
-      {
-        text: "Examples",
+    sidebar: {
+      "/guide/": {
         items: [
-          { text: "Markdown Examples", link: "/markdown-examples" },
-          { text: "Runtime API Examples", link: "/api-examples" },
+          {
+            base: "/guide/",
+            text: "Getting started",
+            items: [
+              { text: "What is ortfo?", link: "/what-is-ortfo" },
+              { text: "Quick start", link: "/getting-started" },
+              { text: "JSON Schemas", link: "/json-schemas" },
+            ],
+          },
+          {
+            base: "/db/",
+            text: "ortfo/db",
+            items: [
+              { text: "Introduction", link: "/" },
+              { text: "Scattered mode", link: "/scattered-mode" },
+              { text: "Exporters", link: "/exporters/" },
+            ],
+          },
         ],
       },
-    ],
+      "/db/": {
+        base: "/db/",
+        items: [
+          {
+            text: "Getting started",
+            link: "/getting-started",
+          },
+					{
+						text: "Your first description.md file",
+						link: "/your-first-description-file"
+					},
+          {
+            text: "Scattered mode",
+            link: "/scattered-mode",
+          },
+          {
+            text: "Markdown",
+            link: "/markdown",
+          },
+          {
+            text: "Database format",
+            link: "/database-format",
+          },
+          {
+            text: "Exporters",
+            base: "/db/exporters/",
+            items: [
+              {
+                text: "Introduction",
+                link: "/",
+              },
+              {
+                text: "Built-in exporters (SSH, FTP, Git, Cloud services)",
+                link: "/builtin",
+              },
+              {
+                text: "The custom exporter",
+                link: "/custom",
+              },
+              {
+                text: "Writing your own exporter",
+                link: "/development",
+              },
+            ],
+          },
+          {
+            text: "CLI Reference",
+            base: "/db/commands/",
+            items: [
+              { text: "Global options", link: "/" },
+              { text: "add", link: "/add" },
+              { text: "build", link: "/build" },
+              { text: "schemas", link: "/schemas" },
+              { text: "replicate", link: "/replicate" },
+              { text: "completion", link: "/completion" },
+            ],
+          },
+
+          {
+            text: "Type definitions for Python, Rust and TypeScript",
+            link: "/client-libraries",
+          },
+        ],
+      },
+    },
 
     socialLinks: [{ icon: "github", link: "https://github.com/ortfo" }],
   },

diff --git a/api-examples.md b/api-examples.md
diff --git a/bun.lockb b/bun.lockb
diff --git a/db/caching.md b/db/caching.md
diff --git a/db/client-libraries.md b/db/client-libraries.md
diff --git a/db/commands/add.md b/db/commands/add.md
diff --git a/db/commands/build.md b/db/commands/build.md
diff --git a/db/commands/completion.md b/db/commands/completion.md
diff --git a/db/commands/global-options.md b/db/commands/global-options.md
diff --git a/db/commands/index.md b/db/commands/index.md
diff --git a/db/commands/replicate.md b/db/commands/replicate.md
diff --git a/db/commands/schemas.md b/db/commands/schemas.md
diff --git a/db/configuration.md b/db/configuration.md
diff --git a/db/database-format.md b/db/database-format.md
diff --git a/db/exporters/builtin.md b/db/exporters/builtin.md
diff --git a/db/exporters/cloud.md b/db/exporters/cloud.md
diff --git a/db/exporters/custom.md b/db/exporters/custom.md
diff --git a/db/exporters/development.md b/db/exporters/development.md
diff --git a/db/exporters/ftp.md b/db/exporters/ftp.md
diff --git a/db/exporters/git.md b/db/exporters/git.md
diff --git a/db/exporters/index.md b/db/exporters/index.md
diff --git a/db/exporters/ssh.md b/db/exporters/ssh.md
diff --git a/db/getting-started.md b/db/getting-started.md
@@ -0,0 +1,31 @@
+---
+next:
+    link: /db/your-first-description-file
+---
+
+# Getting started
+## Installation
+### Binaries
+
+You can download the latest binaries from the [releases page](https://github.com/ortfo/db/releases).
+
+### Using `go`
+
+```bash
+go install github.com/ortfo/db/cmd@latest
+```
+
+### Building from source
+
+#### Requirements
+
+- [Go](https://go.dev)
+- [Just](https://just.systems): a modern alternative to Makefiles[^1]. See [Just's docs on installation](https://github.com/casey/just?tab=readme-ov-file#installation)
+
+#### Steps
+
+1. Clone the repository: `git clone https://github.com/ewen-lbh/portfoliodb`
+2. `cd` into it: `cd portfoliodb`
+3. Compile & install in `~/.local/bin/` `just install`... or simply build a binary to your working directory: `just build`.
+
+[^1]: One big advantage of Just is that it works painlessly on Windows.
diff --git a/db/index.md b/db/index.md
@@ -0,0 +1,3 @@
+# ortfo/db
+
+ortfo's database management system.
diff --git a/db/internationalization.md b/db/internationalization.md
diff --git a/db/json-schemas.md b/db/json-schemas.md
diff --git a/db/layouts.md b/db/layouts.md
diff --git a/db/markdown.md b/db/markdown.md
diff --git a/db/scattered-mode.md b/db/scattered-mode.md
@@ -0,0 +1,42 @@
+# Scattered mode
+
+If you prefer, you can store your description.md files alongside your projects themselves, instead of having everything in a single folder. This use case is referred to as "Scattered mode". Use the `--scattered` [global flag](/db/commands/global-options.md) to enable it.
+
+This mode expects you to have all of your projects stored in a single directory (with each project being its own folder in that directory). Then, your description.md file (and potentially other resources like screenshots or photos of the work) live in a `.ortfo` folder that's in the projects' folders.
+
+Take the following example tree:
+
+```directory-tree
+database/
+├── helloworld
+│   ├── logo.png
+│   └── description.md
+├── resume
+│   └── description.md
+├── portfolio
+│   └── description.md
+└── hackernews-clone
+    └── description.md
+```
+
+Using scattered mode, that tree would instead look like this:
+
+```directory-tree
+projects/
+├── helloworld
+│   ├── .ortfo
+│   │   ├── logo.png
+│   │   └── description.md
+│   └── main.py
+├── resume
+│   └── .ortfo
+│       └── description.md
+├── portfolio
+│   └── .ortfo
+│       └── description.md
+└── hackernews-clone
+    └── .ortfo
+        └── description.md
+```
+
+Of course, your actual project files are still where they are and are left untouched (like the main.py file in the above example)
diff --git a/db/your-first-description-file.md b/db/your-first-description-file.md
@@ -0,0 +1,138 @@
+# Your First `description.md` file
+
+
+## Where do I put it???
+
+Your database is a folder, which has one folder per work in it.
+In each folder, you'll have a markdown file, called `description.md`, describing your work, and other files relevant to the work (images, PDFs, audio files, videos, etc.).
+
+Here's an example tree:
+
+```directory-tree
+database/
+├── helloworld
+│   ├── logo.png
+│   └── description.md
+├── resume
+│   └── description.md
+├── portfolio
+│   └── description.md
+└── hackernews-clone
+    └── description.md
+```
+
+"Building" your database is just translating that easy-to-maintain and natural directory tree to a single JSON file, easily consummable by your frontend website. This way, you can add new projects to your portfolio without having to write a single line of code: just create a new folder, describe your project, build the database, upload it, and done!
+
+::: tip
+If you prefer to put your description files alongside your projects themselves instead of having everything in a central folder somewhere else, check out [Scattered mode](/db/scattered-mode).
+:::
+
+## What do I write in it?
+
+### An example
+
+Here's an example of a typical `description.md` file:
+
+```md
+---
+started: 2023-04-12
+tags: [web, design, ux, ui]
+made with: [figma, react, go]
+---
+
+# My awesome project
+
+This is a paragraph of text. It can contain **bold**, *italic*, and [links](https://example.com).
+
+![](./demo.mp4 "Some caption")
+
+[Link to the source code](https://github.com/ortfo/db)
+```
+
+Description files are separated in "blocks": blocks are separated by an empty line.
+There are:
+
+- [blocks of text (paragraphs)](#paragraphs)
+- [embed declarations (images, videos, audio files, PDFs, etc.)](#media)
+- [(isolated) links](#links): useful for linking to other places where the work appears, e.g. a marketplace where to work is sold, a source code repository, etc.
+
+You can also translate your description.md file into multiple languages by using [language markers](/db/internationalization#language-markers).
+
+Start your file with a top-level header `# Like this` to give your work a title (it can differ from the folder's name, since the folder name is used as the work's identifier, and is guaranteed to be unique).
+
+#### Paragraphs
+
+
+```markdown{9}
+---
+started: 2023-04-12
+tags: [web, design, ux, ui]
+made with: [figma, react, go]
+---
+
+# My awesome project
+
+This is a paragraph of text. It can contain **bold**, *italic*, and [links](https://example.com).
+
+![](./demo.mp4 "Some caption")
+
+[Link to the source code](https://github.com/ortfo/db)
+```
+
+These blocks allow you to write some text using an extended markdown syntax, adding support for abbreviations and footnotes.
+
+#### Media
+
+```markdown{11}
+---
+started: 2023-04-12
+tags: [web, design, ux, ui]
+made with: [figma, react, go]
+---
+
+# My awesome project
+
+This is a paragraph of text. It can contain **bold**, *italic*, and [links](https://example.com).
+
+![](./demo.mp4 "Some caption")
+
+[Link to the source code](https://github.com/ortfo/db)
+```
+
+A "media" block allows you to declare files embedded in your page: YouTube videos, local files, etc.
+
+With native markdown, you can only declare embeds for _images_. We abuse the syntax to extend it to _any file you want_.
+
+```markdown
+![alt text "title"](./demo.mp4)
+```
+
+`source` can be a relative path, an absolute one or a URL.
+
+When building, the compiler will look for these files and analyze them to determine useful metadata such as the dimensions, the duration, whether the media has sound, etc.
+
+#### Links
+
+```markdown{13}
+---
+started: 2023-04-12
+tags: [web, design, ux, ui]
+made with: [figma, react, go]
+---
+
+# My awesome project
+
+This is a paragraph of text. It can contain **bold**, *italic*, and [links](https://example.com).
+
+![](./demo.mp4 "Some caption")
+
+[Link to the source code](https://github.com/ortfo/db)
+```
+
+Of course, you can use links inside of a paragraphs, but you can also declare isolated links that don't need context to be meaningful. Here are some use cases:
+
+- For a website, you can link to the source code repository and the website itself,
+- For a t-shirt, you can link to a marketplace so that people viewing that work can buy it
+- and plenty of other use cases
+
+Having links by themselves allows you to put emphasis on them (maybe display them as buttons), or even display them in a different place than the rest of the content.
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		# ortfo/db

		ortfo's database management system.