diff --git a/Justfile b/Justfile index 280f196..0c492ec 100644 --- a/Justfile +++ b/Justfile @@ -14,8 +14,10 @@ install: chmod +x ~/.local/bin/ortfodb docs: - mkdir -p docs manpages + mkdir -p docs/commands manpages ./ortfodb makedocs + mv docs/*.md docs/commands/ + cp CHANGELOG.md docs/changelog.md render-demo-gif: #!/usr/bin/env bash diff --git a/docs/README.md b/docs/README.md deleted file mode 100644 index d57825b..0000000 --- a/docs/README.md +++ /dev/null @@ -1,3 +0,0 @@ -# Documentation of ortfo/db - -See for the complete documentation. diff --git a/docs/building.md b/docs/building.md new file mode 100644 index 0000000..a57cb37 --- /dev/null +++ b/docs/building.md @@ -0,0 +1,106 @@ +--- +next: false +--- + +# Running ortfo/db + +## Building your database + +Make sure that ortfodb in [installed](/db/getting-started.md#installation). + +Open up a terminal, and run the following: + +::: code-group + +```sh [Regular mode] +ortfodb build database.json +``` + +```sh [Scattered mode] +ortfodb --scattered build database.json +``` + +::: + +You should get the following output: + +```ansi + Writing default configuration file at ortfodb.yaml + Warning default configuration assumes that your projects + live in /mnt/datacore/projects/ortfo/website. + Change this with projects at in the generated configuration file + Info No configuration file found. The default configuration was used. + Finished compiling to database.json +``` + +Subsequent runs of this command will be faster as long as you re-use the output file: ortfo/db will only recompile the projects that have changed since the last run. + +Notice the warning. If you ran the previous command from the directory that contains all of your projects, you should be fine. But if you ran it from somwhere else, you'll probably want to change that `projects at` setting it's talking about to point it to where your projects are. + + +## Tweaking the configuration file + +Open up `ortfodb.yaml` in your favorite text editor. + +It should look a little like this: + +```yaml +extract colors: + enabled: true + extract: [] + default files: [] +make gifs: + enabled: false + file name template: "" +make thumbnails: + enabled: true + sizes: + - 100 + - 400 + - 600 + - 1200 + input file: "" + file name template: /@.webp +build metadata file: .lastbuild.yaml +media: + at: media/ +scattered mode folder: .ortfo +tags: + repository: "" +technologies: + repository: "" +projects at: /home/you +``` + +The config file that ortfo/db generated for you has mostly sensible defaults. The most important things to check are: + +`projects at` +: The path to the directory that contains all of your projects + +`media.at` +: Where to copy all the media files you reference in your description.md files, as well as the [generated thumbnails](/db/thumbnails) + +Most other options relate to certain features, you'll find documentation about them in the pages relating to the features themselves. + +::: tip TODO +TODO: Document the whole config file in one place +::: + +## What now? + +Congrats, you've setup ortfo/db! + +Next steps: + +What to know all the data contained in your database? +: Check out [the database format](/db/database-format.md) + +Want to learn more about the different features ortfo/db has to offer? +: Check out the [features page](/db/features.md) + +Wanna integrate ortfo/db with a static site generator? +: See the [Static site generator exporters](/db/exporters/static-site-generators.md) + +Curious about how ortfo/db is used to actually make a portfolio site? +: Check out [the repository](https://github.com/ewen-lbh/portfolio) for [my own portfolio](https://ewen.works), which is (of course) built with ortfo/db. +: You can also see how [net7](https://github.com/inp-net) uses ortfo/db to keep their [projects page](https://net7.dev/realisation.html) up to date: see [the repository](https://git.inpt.fr/net7/website/-/tree/master?ref_type=heads) (warning: french ahead) diff --git a/docs/caching.md b/docs/caching.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/changelog.md b/docs/changelog.md new file mode 100644 index 0000000..53dd63f --- /dev/null +++ b/docs/changelog.md @@ -0,0 +1,11 @@ +--- +editLink: false +--- + + + + +
diff --git a/docs/client-libraries-versions.js b/docs/client-libraries-versions.js new file mode 100644 index 0000000..56d0428 --- /dev/null +++ b/docs/client-libraries-versions.js @@ -0,0 +1,70 @@ +export async function getRustVersion(localFilename = "") { + try { + const version = await fetch(`https://crates.io/api/v1/crates/ortfodb`) + .then((res) => res.json()) + .then((data) => data.crate.max_version) + console.info(`Got Rust version from crates.io API: ${version}`) + return version + } catch (error) { + if (localFilename) { + const fs = await import("node:fs") + console.error(`Failed to get Rust version from crates.io API: ${error}`) + console.info(`Falling back to reading from ortfodb Cargo.toml file`) + const contents = fs.readFileSync(localFilename, "utf-8") + return contents.match(/version = "(.+)"/)[1] + } else { + throw error + } + } +} + +export async function getGemVersion(localFilename = "") { + try { + const version = await fetch( + `https://rubygems.org/api/v1/versions/ortfodb/latest.json` + ) + .then((res) => res.json()) + .then((data) => data.version) + + console.info(`Got RubyGem version from API: ${version}`) + return version + } catch (error) { + if (localFilename) { + const fs = await import("node:fs") + console.error(`Failed to get RubyGem version from API: ${error}`) + console.info( + `Falling back to reading from ortfodb submodule version.rb file` + ) + const contents = fs.readFileSync(localFilename, "utf-8") + return contents.match(/VERSION = "(.+)"/)[1] + } else { + throw error + } + } +} + +export async function getGoVersion(localFilename) { + const packageName = "github.com/ortfo/db" + + try { + const response = await fetch( + `https://proxy.golang.org/${packageName}/@latest` + ) + const data = await response.json() + if (data.Version) { + console.info(`Got Go version from proxy.golang.org: ${data.Version}`) + return data.Version + } else { + throw new Error(`Version not found for package ${packageName}`) + } + } catch (error) { + console.info(`Falling back to reading from local file ${localFilename}`) + const contents = fs.readFileSync(localFilename, "utf-8") + const match = contents.match(/const Version = "(.+)"/) + if (match) { + return match[1] + } else { + throw new Error(`Version not found in ${localFilename}`) + } + } +} diff --git a/docs/client-libraries.data.js b/docs/client-libraries.data.js new file mode 100644 index 0000000..e1166c1 --- /dev/null +++ b/docs/client-libraries.data.js @@ -0,0 +1,18 @@ +import { getGemVersion, getGoVersion, getRustVersion } from "./client-libraries-versions" + +export default { + watch: [ + "ortfodb/packages/ruby/lib/ortfodb/version.rb", + "ortfodb/packages/rust/Cargo.toml", + "ortfodb/meta.go" + ], + async load(watchedFiles) { + return { + versions: { + gem: await getGemVersion(watchedFiles[0]), + rust: await getRustVersion(watchedFiles[1]), + go: await getGoVersion(watchedFiles[2]), + }, + } + }, +} diff --git a/docs/client-libraries.md b/docs/client-libraries.md new file mode 100644 index 0000000..b5ad24c --- /dev/null +++ b/docs/client-libraries.md @@ -0,0 +1,213 @@ +--- +outline: [2, 3] +--- + + + +# Client libraries + +
+ + + PyPI + + + + npm + + + + RubyGems + + + + Packagist + + + + Crates.io + + + + Go + + +
+ +ortfo/db exports its type definitions for use in various programming languages. This is mainly useful to access data from the exported database.json file in a type-safe way. + +It's like an [ORM](https://en.wikipedia.org/wiki/Object-relational_mapping), but for your JSON database! + +## Available clients + +### Python + +#### Installation + +Install `ortfodb` [on pypi.org](https://pypi.org/project/ortfodb/): + +::: code-group + +```bash [with pip] +pip install ortfodb +``` + +```bash [with Poetry] +poetry add ortfodb +``` + +::: + +#### Usage + +```python +from ortfodb import database_from_dict +import json + +with open("path/to/the/database.json") as f: + database = database_from_dict(json.load(f)) +``` + +### TypeScript (and JavaScript) + +#### Installation + +Install `@ortfo/db` [on npmjs.com](https://www.npmjs.com/package/@ortfo/db): + +::: code-group + +```bash [with npm] +npm install @ortfo/db +``` + +```bash [with yarn] +yarn add @ortfo/db +``` + +```bash [with pnpm] +pnpm add @ortfo/db +``` + +```bash [with bun] +bun add ortfodb +``` + +::: + +#### Usage + +```typescript +import { Database } from "@ortfo/db"; + +const database = Database.toDatabase(jsonStringOfTheDatabase); +``` + +### Ruby + +#### Installation + +Install `ortfodb` [on rubygems.org](https://rubygems.org/gems/ortfodb): + +::: code-group + +```ruby-vue [Gemfile] +gem 'ortfodb', '~> {{ versions.gem }}' +``` + +```ruby-vue{4} [my_gem.gemspec] +Gem::Specification.new do |spec| + spec.name = 'my_gem' + ... + spec.add_dependency 'ortfodb', '~> {{ versions.gem }}' +end +``` + +::: + +#### Usage + +```ruby +require 'ortfodb/database' + +database = Ortfodb::Database.from_json! json_string +``` + +### Rust + +#### Installation + +Install `ortfodb` [on crates.io](https://crates.io/crates/ortfodb): + +::: code-group + +```bash [with cargo] +cargo add ortfodb +``` + +```toml-vue [Cargo.toml] +[dependencies] +ortfodb = "{{ versions.rust }}" +``` + +::: + +#### Usage + +```rust +use ortfodb::Database; + +let database: Database = serde_json::from_str(&json_string).unwrap(); +``` + +### PHP + +See https://github.com/ortfo/db/tree/main/packages/php + +::: warning +It's not on Packagist yet because packagist expects a `composer.json` file at the root of the repository +::: + +#### Installation + +TODO + +#### Usage + +::: warning +I haven't programmed in PHP in a while, so this might be wrong. Please open an issue if you find a mistake. +::: + +```php + + +
On ewen.works
+ + +## Configuration + +Enable it in [`ortfodb.yaml`](/db/configuration.md): + +```yaml +extract colors: + enabled: true + extract: [] + default files: [] +``` + +### `enabled` + +Controls whether ortfo/db will try to extract colors or not + +### `extract` + +Array of + +### `default files` + +TODO + +## In `database.json` + +Each media [content block](/db/your-first-description-file.md#blocks) will have a `colors` object that contains the proeminent colors of the media: + +```json +{ + "ideaseed": { + "content": { + "en": { + "blocks": [ + { + "id": "Sw0WJU8osY", + "type": "media", + ... + "hasSound": false, + "colors": {// [!code focus] + "primary": "#FEF3ED",// [!code focus] + "secondary": "#858585",// [!code focus] + "tertiary": "#FCC696" // [!code focus] + }, // [!code focus] + "thumbnails": { + "100": "ideaseed/Sw0WJU8osY@100.webp", + ... +``` diff --git a/docs/add.md b/docs/commands/add.md similarity index 100% rename from docs/add.md rename to docs/commands/add.md diff --git a/docs/build.md b/docs/commands/build.md similarity index 100% rename from docs/build.md rename to docs/commands/build.md diff --git a/docs/exporters-doc.md b/docs/commands/exporters-doc.md similarity index 88% rename from docs/exporters-doc.md rename to docs/commands/exporters-doc.md index a638d5b..bdafd3d 100644 --- a/docs/exporters-doc.md +++ b/docs/commands/exporters-doc.md @@ -15,7 +15,10 @@ ortfodb exporters doc [flags] ```ansi $ ortfodb exporters help localize -localize  Export separately the database as a single database for each language. The `content` field of each work is localized, meaning it's not an object mapping languages to localized content, but the content directly, in the language. +localize  Export separately the database as a single database for each language. +The `content` field of each work is localized, meaning it's not an +object mapping languages to localized content, but the content +directly, in the language.  Options:  โ€ข filename_template  diff --git a/docs/exporters-init.md b/docs/commands/exporters-init.md similarity index 100% rename from docs/exporters-init.md rename to docs/commands/exporters-init.md diff --git a/docs/exporters-list.md b/docs/commands/exporters-list.md similarity index 100% rename from docs/exporters-list.md rename to docs/commands/exporters-list.md diff --git a/docs/exporters.md b/docs/commands/exporters.md similarity index 100% rename from docs/exporters.md rename to docs/commands/exporters.md diff --git a/docs/global-options.md b/docs/commands/global-options.md similarity index 100% rename from docs/global-options.md rename to docs/commands/global-options.md diff --git a/docs/replicate.md b/docs/commands/replicate.md similarity index 100% rename from docs/replicate.md rename to docs/commands/replicate.md diff --git a/docs/schemas.md b/docs/commands/schemas.md similarity index 100% rename from docs/schemas.md rename to docs/commands/schemas.md diff --git a/docs/configuration.md b/docs/configuration.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/database-format.md b/docs/database-format.md new file mode 100644 index 0000000..8da6ab6 --- /dev/null +++ b/docs/database-format.md @@ -0,0 +1,183 @@ +# Database format + +The result of ortfo/db's build process is a `database.json` file. This file contains all of the projects that were processed. + +## Missing values + +All fields described here are _always_ present. If they are irrelevant or unknown, they are set to their [zero value](https://go.dev/tour/basics/12). Basically, numbers are `0`, strings are `""`, arrays are `[]`, and objects are `{}`. + +::: warning +There's currently a bug where objects are `null` instead of `{}`. This will be fixed in a future release. This is because Go's zero value of maps is `nil` instead of an empty map. +::: + +## Structure + + + +The database is a JSON-encoded object that map works' IDs to objects containing the following fields: + +ID +: The ID of the work[^2]. IDs of works are simply their folders' names, since those a guaranteed to be unique + +buildAt +: The date at which the work was last built. Useful for caching purposes + +descriptionHash +: A hash of the work's description file. Again, useful for caching purposes + +metadata +: See [Metadata](#metadata) + +content +: An object that maps language codes (see [Internationalization](/db/internationalization.md)) to the [work's content](#content). +: If you don't translate your descriptions to other languages, the single key in the object will be `default`. + +Partial +: `true` if the work was not fully built (e.g. if the build process was interrupted while processing that work), `false` otherwise + +[^2]: This is technically redundant, but useful when you only have a single object and need to get the ID of the work + +### Metadata + +Contains data about the work that is not part of the description itself, such as the date of creation, etc. + +Most of these fields are set by the user in the description file's front-matter. + +#### aliases + +Array of strings that are other IDs that point to this work. Useful to express redirections. For example, if a work with ID `ortfo` has `["ortfodb", "ortfomk"]` as the `aliases` field, then going to `ortfodb`'s page should redirect to `ortfo`'s page + +#### finished + +Date when the work was finished. Should be in the format `YYYY-MM-DD` + +#### started + +Date when the work was started. Should be in the format `YYYY-MM-DD` + +#### tags + +Array of strings that represent the [tags](/db/tags.md) of the work. + +#### madeWith + +_(`made with` or `using` in the description file)_ + +Array of strings that represent the [technologies](/db/technologies.md) (in the very broad sense, this could be stuff like "oil paint" when the work is a painting, or "sveltekit" when it's a website) used to make the work. + +#### thumbnail + +Path, relative to the folder where the description.md file is, to the work's thumbnail. Useful to determine which media content block to use as the work's thumbnail + +#### colors + +Useful to express colors to use for that project. Might be filled automatically with [Color extraction](/db/colors.md) when not manually set by the user + +#### pageBackground + +_(`page background` in the description file)_ + +Path, relative to the folder where the description.md file is, to the work's background image. Useful to determine which media content block to use as the work pages's background image, for example + +#### wip + +Whether the project is considered a "Work in progress" or not + +#### private + +Whether the project is marked as private or not. Useful to hide works that are not ready to be shown yet, or to have "unlisted" works + +#### additionalMetadata + +Object that contains other metadata set by the user in the description file. + +::: warning +There's currently a bug that makes `madeWith`'s actual value appear here as `made_with`. This will be fixed in a future release. +::: + +### Content + +#### title + +The works' title. This correspond's to the first-level header (`# Like this`) in the description file + +#### footnotes + +Maps footnote references to their definitions. See [Footnotes](/db/markdown.md#footnotes) + +#### layout + +A two-dimensional array that represents the layout of the work. Each element of the array is a string that represents a [content block](#blocks)'s ID. + +_See [Layouts](/db/layouts.md)_ + +#### blocks + +Array of content blocks. + +id +: The ID of the block. IDs of blocks are generated by the compiler and are guaranteed to be unique per work + +anchor +: A human-readable unique identifier that can be used to create an [anchor tag](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attr-name) to that block. Might be empty + +index +: The position of that block in the description.md file. Starts at 0. + +type +: `paragraph` when the block is a [Paragraph block](#paragraph-blocks) +: `media` when the block is a [Media block](#media-blocks) +: `link` when the block is a [Link block](#link-blocks) + +_other fields depend on `type`_ +: See just below + +##### Paragraph blocks + +content +: The HTML content of that paragraph. See [Markdown](/db/markdown.md) for more information about how the markdown syntax is processed, and what markdown features are handled by ortfo/db. + +##### Media blocks + +TODO. See [the go documentation for `Media`](https://pkg.go.dev/github.com/ortfo/db#Media) in the meantime. + +Here are the attributes: + +```go +Alt string `json:"alt"` +Caption string `json:"caption"` +RelativeSource FilePathInsidePortfolioFolder `json:"relativeSource"` +DistSource FilePathInsideMediaRoot `json:"distSource"` +ContentType string `json:"contentType"` +Size int `json:"size"` // in bytes +Dimensions ImageDimensions `json:"dimensions"` +Online bool `json:"online"` +Duration float64 `json:"duration"` // in seconds +HasSound bool `json:"hasSound"` +Colors ColorPalette `json:"colors"` +Thumbnails ThumbnailsMap `json:"thumbnails"` +ThumbnailsBuiltAt string `json:"thumbnailsBuiltAt"` +Attributes MediaAttributes `json:"attributes"` +Analyzed bool `json:"analyzed"` // whether the media has been analyzed +``` + + +##### Link blocks + +text +: The text of the link. May contain HTML. + +title +: The link's title, to be used as the `title` attribute of the `` tag + +url +: The URL the link points to + +## Schema & type definitions + +JSON Schema +: See [JSON Schemas](/db/json-schemas.md) + +Type definitions +: For Go code, see the [github.com/ortfo/db package](https://pkg.go.dev/github.com/ortfo/db) +: For other languages, see [Client libraries](/db/client-libraries.md) diff --git a/docs/exporters/custom.md b/docs/exporters/custom.md new file mode 100644 index 0000000..3660e70 --- /dev/null +++ b/docs/exporters/custom.md @@ -0,0 +1,24 @@ + +# The `custom` exporter + +A convinient way to run your own shell commands at various stages of the build process, without having to [create your own](./development.md) exporter in a separate YAML file. + +## Configuration + +The configuration of the custom exporter corresponds to the fields used to [create an exporter](./development.md#yaml-exporters): + + + +### Exporter command + + + +### Example + +```yaml +exporters: + custom: + after: + - run: echo {{ .Database | len }} works in the resulting database diff --git a/docs/exporters/development.md b/docs/exporters/development.md new file mode 100644 index 0000000..113e766 --- /dev/null +++ b/docs/exporters/development.md @@ -0,0 +1,52 @@ + + +# Exporters development guide + +## Two types of exporters + +ortfo/db has two types of exporters, with different levels of complexity and expressive power: + +YAML exporters +: Most of the exporters can be expressed that way. This does not require any development environment setup, but only allows running shell commands. + +Go exporters +: For more complex exporters, you can write a Go program that implements the `Exporter` interface. However, for now, Go exporters can only be made available to ortfo by [contributing to the project](https://github.com/ortfo/db). + +## YAML exporters + +### Bootstrapping + +You can quickly initialize an example exporter by running + +```shellsession +ortfodb exporters init my-exporter +``` + +content blocks in interesting ways + link: /db/layouts + icon: ๐Ÿ“ + - title: Internationalization + details: Translate your portfolio into multiple languages + link: /db/internationalization + icon: ๐ŸŒ + - title: Client libraries + details: Use the generated database in your code with autocompletion and type safety + link: /db/client-libraries + icon: ๐Ÿ“š + - title: Exporters + details: Send your database file to a web server, a cloud storage service, or use it in your favorite static site generator + link: /db/exporters + icon: ๐Ÿงฉ + - title: JSON Schemas + details: Great editing experience for ortfo/db's YAML files + link: /db/json-schemas + icon: ๐Ÿ“œ + - title: Command-line interface + details: ortfo/db works with a command-line interface, making it easy to automate your portfolio's generation and integrate with other tools. + link: /db/commands/global-options + icon: ๐Ÿค“ +--- diff --git a/docs/getting-started.md b/docs/getting-started.md new file mode 100644 index 0000000..8989f22 --- /dev/null +++ b/docs/getting-started.md @@ -0,0 +1,150 @@ +# Getting started +## Installation +### Binaries + +You can download the latest binaries for Linux, MacOS and Windows from the [releases page](https://github.com/ortfo/db/releases/latest). + +Windows +: [64-bit (use this if you don't know)](https://github.com/ortfo/db/releases/latest/download/ortfodb_windows_amd64.exe) +: [32-bit (older computers)](https://github.com/ortfo/db/releases/latest/download/ortfodb_windows_386.exe) + +Mac OS +: [64-bit](https://github.com/ortfo/db/releases/latest/download/ortfodb_darwin_amd64) +: [ARM64 (M1 Macs)](https://github.com/ortfo/db/releases/latest/download/ortfodb_darwin_arm64) + +Linux +: [64-bit](https://github.com/ortfo/db/releases/latest/download/ortfodb_linux_amd64) +: [32-bit (older computers)](https://github.com/ortfo/db/releases/latest/download/ortfodb_linux_386) +: [ARM64 (Raspberry Pi, etc.)](https://github.com/ortfo/db/releases/latest/download/ortfodb_linux_arm64) + + +### Package managers + +::: tip +Package files are also available to download from [Github Releases](https://github.com/ortfo/db/releases), in case the package manager's repositories are not up-to-date enough +::: + +::: warning +This is my first time packaging a program to practically all package managers. I'm not familiar with most of them. If the installation does not work, please [open an issue](https://github.com/ortfo/db/issues/new). +::: + +#### Linux + +##### Distro-specific + +::: code-group + +```bash [Arch Linux (AUR)] +paru -S ortfodb-bin +``` + +```bash [Ubuntu, Debian] +echo "deb [trusted=yes] https://deb.ortfo.org/ /" | sudo tee /etc/apt/sources.list.d/ortfo.list +sudo apt update +sudo apt install ortfodb +``` + +```bash [Fedora] +# waiting on https://github.com/goreleaser/goreleaser/issues/3136 to add it to COPR +sudo dnf -y install dnf-plugins-core +sudo dnf config-manager --add-repo https://rpm.ortfo.org/ +# rpm.ortfo.org is not signed yet, so we need to disable GPG checks +sudo dnf --nogpgcheck install ortfodb +``` + +```bash [Alpine Linux] +# not available yet +# look for a .apk file in the github releases +# apk add ortfodb +``` + +```bash [Termux] +# not available yet +# look for a .termux.deb file in the github releases +# pkg install ortfodb +# using Ubuntu's install instructions may work, idk +``` + +```bash [Nix] +# coming soonโ„ข +``` + +::: + +##### Universal + +::: code-group + +```bash [Snap] +# coming soonโ„ข +``` + +```bash [Flatpak] +# coming soonโ„ข +``` + +```bash [AppImage] +# coming soonโ„ข +``` + +```bash [Homebrew] +# on its own tap for the moment +brew tap ortfo/brew-ortfodb/ortfodb +brew install ortfodb +``` + +::: + +#### MacOS + +::: code-group + +```bash [Homebrew] +# on its own tap for the moment +brew tap ortfo/brew-ortfodb/ortfodb +brew install ortfodb +``` + +::: + +#### Windows + +::: code-group + +```powershell [WinGet] +# To be submitted, not yet available +# winget install ortfo.db +``` + +```powershell [Scoop] +# not on official repos yet +scoop bucket add https://github.com/ortfo/scoop-ortfodb +scoop install ortfodb +``` + +```powershell [Chocolatey] +# not yet avaiable: needs to be on windows to build the packageโ€ฆ +``` + +::: + +### 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/docs/image-formats.md b/docs/image-formats.md new file mode 100644 index 0000000..9027669 --- /dev/null +++ b/docs/image-formats.md @@ -0,0 +1,315 @@ +# Supported Image Formats + +Under the hood, we use the [ImageMagick](https://imagemagick.org/index.php) library to analyze images. This allows us to support a wide range of image formats. + +## Available formats + +While this may vary from system to system, the following formats are generally supported: + +```shellsession +$ magick identify -list format + Format Module Mode Description +------------------------------------------------------------------------------- + 3FR DNG r-- Hasselblad CFV/H3D39II Raw Format (0.21.2-Release) + 3G2 VIDEO r-- Media Container + 3GP VIDEO r-- Media Container + AAI* AAI rw+ AAI Dune image + AI PDF rw- Adobe Illustrator CS2 + APNG VIDEO rw+ Animated Portable Network Graphics + ART* ART rw- PFS: 1st Publisher Clip Art + ARW DNG r-- Sony Alpha Raw Format (0.21.2-Release) + ASHLAR* ASHLAR -w+ Image sequence laid out in continuous irregular courses + AVI VIDEO r-- Microsoft Audio/Visual Interleaved + AVIF HEIC rw+ AV1 Image File Format (1.17.6) + AVS* AVS rw+ AVS X image + BAYER* BAYER rw+ Raw mosaiced samples + BAYERA* BAYER rw+ Raw mosaiced and alpha samples + BGR* BGR rw+ Raw blue, green, and red samples + BGRA* BGR rw+ Raw blue, green, red, and alpha samples + BGRO* BGR rw+ Raw blue, green, red, and opacity samples + BIE* JBIG rw- Joint Bi-level Image experts Group interchange format (2.1) + BMP* BMP rw- Microsoft Windows bitmap image + BMP2* BMP rw- Microsoft Windows bitmap image (V2) + BMP3* BMP rw- Microsoft Windows bitmap image (V3) + BRF* BRAILLE -w- BRF ASCII Braille format + CAL* CALS rw- Continuous Acquisition and Life-cycle Support Type 1 + Specified in MIL-R-28002 and MIL-PRF-28002 + CALS* CALS rw- Continuous Acquisition and Life-cycle Support Type 1 + Specified in MIL-R-28002 and MIL-PRF-28002 + CANVAS* XC r-- Constant image uniform color + CAPTION* CAPTION r-- Caption + CIN* CIN rw- Cineon Image File + CIP* CIP -w- Cisco IP phone image format + CLIP* CLIP rw+ Image Clip Mask + CMYK* CMYK rw+ Raw cyan, magenta, yellow, and black samples + CMYKA* CMYK rw+ Raw cyan, magenta, yellow, black, and alpha samples + CR2 DNG r-- Canon Digital Camera Raw Format (0.21.2-Release) + CR3 DNG r-- Canon Digital Camera Raw Format (0.21.2-Release) + CRW DNG r-- Canon Digital Camera Raw Format (0.21.2-Release) + CUBE* CUBE r-- Cube LUT + CUR* ICON rw- Microsoft icon + CUT* CUT r-- DR Halo + DATA* INLINE rw+ Base64-encoded inline images + DCM* DCM r-- Digital Imaging and Communications in Medicine image + DICOM is used by the medical community for images like X-rays. The + specification, "Digital Imaging and Communications in Medicine + (DICOM)", is available at http://medical.nema.org/. In particular, + see part 5 which describes the image encoding (RLE, JPEG, JPEG-LS), + and supplement 61 which adds JPEG-2000 encoding. + DCR DNG r-- Kodak Digital Camera Raw Format (0.21.2-Release) + DCRAW DNG r-- Raw Photo Decoder (dcraw) (0.21.2-Release) + DCX* PCX rw+ ZSoft IBM PC multi-page Paintbrush + DDS* DDS rw+ Microsoft DirectDraw Surface + DFONT* TTF r-- Multi-face font package (Freetype 2.13.2) + DNG DNG r-- Digital Negative Raw Format (0.21.2-Release) + DOT DOT --- Graphviz + DPX* DPX rw- SMPTE 268M-2003 (DPX 2.0) + Digital Moving Picture Exchange Bitmap, Version 2.0. + See SMPTE 268M-2003 specification at http://www.smtpe.org + + DXT1* DDS rw+ Microsoft DirectDraw Surface + DXT5* DDS rw+ Microsoft DirectDraw Surface + EPDF PDF rw- Encapsulated Portable Document Format + EPI PS rw- Encapsulated PostScript Interchange format + EPS PS rw- Encapsulated PostScript + EPS2 PS2 -w- Level II Encapsulated PostScript + EPS3 PS3 -w+ Level III Encapsulated PostScript + EPSF PS rw- Encapsulated PostScript + EPSI PS rw- Encapsulated PostScript Interchange format + EPT EPT rw- Encapsulated PostScript with TIFF preview + EPT2 EPT rw- Encapsulated PostScript Level II with TIFF preview + EPT3 EPT rw+ Encapsulated PostScript Level III with TIFF preview + ERF DNG r-- Epson Raw Format (0.21.2-Release) + EXR EXR rw- High Dynamic-range (HDR) (OpenEXR 3.2.4) + FARBFELD* FARBFELD rw- Farbfeld + FAX* FAX rw+ Group 3 FAX + FAX machines use non-square pixels which are 1.5 times wider than + they are tall but computer displays use square pixels, therefore + FAX images may appear to be narrow unless they are explicitly + resized using a geometry of "150x100%". + + FF* FARBFELD rw- Farbfeld + FFF DNG r-- Hasselblad CFV/H3D39II Raw Format (0.21.2-Release) + FILE* URL r-- Uniform Resource Locator (file://) + FITS* FITS rw+ Flexible Image Transport System + FL32* FL32 rw- FilmLight + FLV VIDEO rw+ Flash Video Stream + FRACTAL* PLASMA r-- Plasma fractal image + FTP* URL --- Uniform Resource Locator (ftp://) + FTS* FITS rw+ Flexible Image Transport System + FTXT* FTXT rw- Formatted text image + G3* FAX rw- Group 3 FAX + G4* FAX rw- Group 4 FAX + GIF* GIF rw+ CompuServe graphics interchange format + GIF87* GIF rw- CompuServe graphics interchange format (version 87a) + GRADIENT* GRADIENT r-- Gradual linear passing from one shade to another + GRAY* GRAY rw+ Raw gray samples + GRAYA* GRAY rw+ Raw gray and alpha samples + GROUP4* TIFF rw- Raw CCITT Group4 + Compression options: None, Fax/Group3, Group4, JBIG, JPEG, LERC, LZW, LZMA, RLE, ZIP, ZSTD, WEBP + GV DOT --- Graphviz + HALD* HALD r-- Identity Hald color lookup table image + HDR* HDR rw+ Radiance RGBE image format + HEIC HEIC rw+ High Efficiency Image Format (1.17.6) + HEIF HEIC rw+ High Efficiency Image Format (1.17.6) +HISTOGRAM* HISTOGRAM -w- Histogram of the image + HRZ* HRZ rw- Slow Scan TeleVision + HTM* HTML -w- Hypertext Markup Language and a client-side image map + HTML* HTML -w- Hypertext Markup Language and a client-side image map + HTTP* URL r-- Uniform Resource Locator (http://) + HTTPS* URL r-- Uniform Resource Locator (https://) + ICB* TGA rw- Truevision Targa image + ICO* ICON rw+ Microsoft icon + ICON* ICON rw- Microsoft icon + IIQ DNG r-- Phase One Raw Format (0.21.2-Release) + INFO INFO -w+ The image format and characteristics + INLINE* INLINE rw+ Base64-encoded inline images + IPL* IPL rw+ IPL Image Sequence + ISOBRL* BRAILLE -w- ISO/TR 11548-1 format + ISOBRL6* BRAILLE -w- ISO/TR 11548-1 format 6dot + J2C* JP2 rw- JPEG-2000 Code Stream Syntax (2.5.2) + J2K* JP2 rw- JPEG-2000 Code Stream Syntax (2.5.2) + JBG* JBIG rw+ Joint Bi-level Image experts Group interchange format (2.1) + JBIG* JBIG rw+ Joint Bi-level Image experts Group interchange format (2.1) + JNG* PNG rw- JPEG Network Graphics + See http://www.libpng.org/pub/mng/ for details about the JNG + format. + JNX* JNX r-- Garmin tile format + JP2* JP2 rw- JPEG-2000 File Format Syntax (2.5.2) + JPC* JP2 rw- JPEG-2000 Code Stream Syntax (2.5.2) + JPE* JPEG rw- Joint Photographic Experts Group JFIF format (libjpeg-turbo 3.0.2) + JPEG* JPEG rw- Joint Photographic Experts Group JFIF format (libjpeg-turbo 3.0.2) + JPG* JPEG rw- Joint Photographic Experts Group JFIF format (libjpeg-turbo 3.0.2) + JPM* JP2 rw- JPEG-2000 File Format Syntax (2.5.2) + JPS* JPEG rw- Joint Photographic Experts Group JFIF format (libjpeg-turbo 3.0.2) + JPT* JP2 rw- JPEG-2000 File Format Syntax (2.5.2) + JSON JSON -w+ The image format and characteristics + JXL* JXL rw+ JPEG XL (ISO/IEC 18181) (libjxl 0.10.2) + K25 DNG r-- Kodak Digital Camera Raw Format (0.21.2-Release) + KDC DNG r-- Kodak Digital Camera Raw Format (0.21.2-Release) + KERNEL* KERNEL -w- Morphology Kernel + LABEL* LABEL r-- Image label + M2V VIDEO rw+ MPEG Video Stream + M4V VIDEO rw+ Raw VIDEO-4 Video + MAC* MAC r-- MAC Paint + MAP* MAP rw- Colormap intensities and indices + MASK* MASK rw+ Image Clip Mask + MAT MAT rw+ MATLAB level 5 image format + MATTE* MATTE -w+ MATTE format + MDC DNG r-- Minolta Digital Camera Raw Format (0.21.2-Release) + MEF DNG r-- Mamiya Raw Format (0.21.2-Release) + MIFF* MIFF rw+ Magick Image File Format + MKV VIDEO rw+ Multimedia Container + MNG* PNG rw+ Multiple-image Network Graphics (libpng 1.6.43) + See http://www.libpng.org/pub/mng/ for details about the MNG + format. + MONO* MONO rw- Raw bi-level bitmap + MOS DNG r-- Aptus Leaf Raw Format (0.21.2-Release) + MOV VIDEO rw+ MPEG Video Stream + MP4 VIDEO rw+ VIDEO-4 Video Stream + MPC* MPC rw+ Magick Pixel Cache image format + MPEG VIDEO rw+ MPEG Video Stream + MPG VIDEO rw+ MPEG Video Stream + MPO* JPEG r-- Joint Photographic Experts Group JFIF format (libjpeg-turbo 3.0.2) + MRW DNG r-- Sony (Minolta) Raw Format (0.21.2-Release) + MSL* MSL rw+ Magick Scripting Language + MSVG* SVG rw+ ImageMagick's own SVG internal renderer + MTV* MTV rw+ MTV Raytracing image format + MVG* MVG rw- Magick Vector Graphics + NEF DNG r-- Nikon Digital SLR Camera Raw Format (0.21.2-Release) + NRW DNG r-- Nikon Digital SLR Camera Raw Format (0.21.2-Release) + NULL* NULL rw- Constant image of uniform color + ORA ORA r-- OpenRaster format + ORF DNG r-- Olympus Digital Camera Raw Format (0.21.2-Release) + OTB* OTB rw- On-the-air bitmap + OTF* TTF r-- Open Type font (Freetype 2.13.2) + PAL* UYVY rw- 16bit/pixel interleaved YUV + PALM* PALM rw+ Palm pixmap + PAM* PNM rw+ Common 2-dimensional bitmap format + PANGO* PANGO r-- Pango Markup Language (Pangocairo 1.52.2) + PATTERN* PATTERN r-- Predefined pattern + PBM* PNM rw+ Portable bitmap format (black and white) + PCD* PCD rw- Photo CD + PCDS* PCD rw- Photo CD + PCL PCL rw+ Printer Control Language + PCT* PICT rw- Apple Macintosh QuickDraw/PICT + PCX* PCX rw- ZSoft IBM PC Paintbrush + PDB* PDB rw+ Palm Database ImageViewer Format + PDF PDF rw+ Portable Document Format + PDFA PDF rw+ Portable Document Archive Format + PEF DNG r-- Pentax Electronic Raw Format (0.21.2-Release) + PES* PES r-- Embrid Embroidery Format + PFA* TTF r-- Postscript Type 1 font (ASCII) (Freetype 2.13.2) + PFB* TTF r-- Postscript Type 1 font (binary) (Freetype 2.13.2) + PFM* PNM rw+ Portable float format + PGM* PNM rw+ Portable graymap format (gray scale) + PGX* PGX rw- JPEG 2000 uncompressed format + PHM* PNM rw+ Portable half float format + PICON* XPM rw- Personal Icon + PICT* PICT rw- Apple Macintosh QuickDraw/PICT + PIX* PIX r-- Alias/Wavefront RLE image format + PJPEG* JPEG rw- Joint Photographic Experts Group JFIF format (libjpeg-turbo 3.0.2) + PLASMA* PLASMA r-- Plasma fractal image + PNG* PNG rw- Portable Network Graphics (libpng 1.6.43) + See http://www.libpng.org/ for details about the PNG format. + PNG00* PNG rw- PNG inheriting bit-depth, color-type from original, if possible + PNG24* PNG rw- opaque or binary transparent 24-bit RGB + PNG32* PNG rw- opaque or transparent 32-bit RGBA + PNG48* PNG rw- opaque or binary transparent 48-bit RGB + PNG64* PNG rw- opaque or transparent 64-bit RGBA + PNG8* PNG rw- 8-bit indexed with optional binary transparency + PNM* PNM rw+ Portable anymap +POCKETMOD PDF rw+ Pocketmod Personal Organizer + PPM* PNM rw+ Portable pixmap format (color) + PS PS rw+ PostScript + PS2 PS2 -w+ Level II PostScript + PS3 PS3 -w+ Level III PostScript + PSB* PSD rw+ Adobe Large Document Format + PSD* PSD rw+ Adobe Photoshop bitmap + PTIF* TIFF rw+ Pyramid encoded TIFF + Compression options: None, Fax/Group3, Group4, JBIG, JPEG, LERC, LZW, LZMA, RLE, ZIP, ZSTD, WEBP + PWP* PWP r-- Seattle Film Works + QOI* QOI rw- Quite OK image format +RADIAL-GRADIENT* GRADIENT r-- Gradual radial passing from one shade to another + RAF DNG r-- Fuji CCD-RAW Graphic Raw Format (0.21.2-Release) + RAS* SUN rw+ SUN Rasterfile + RAW DNG r-- Raw (0.21.2-Release) + RGB* RGB rw+ Raw red, green, and blue samples + RGB565* RGB r-- Raw red, green, blue samples in 565 format + RGBA* RGB rw+ Raw red, green, blue, and alpha samples + RGBO* RGB rw+ Raw red, green, blue, and opacity samples + RGF* RGF rw- LEGO Mindstorms EV3 Robot Graphic Format (black and white) + RLA* RLA r-- Alias/Wavefront image + RLE* RLE r-- Utah Run length encoded image + RMF DNG r-- Raw Media Format (0.21.2-Release) + RSVG* SVG rw+ Librsvg SVG renderer (RSVG 2.58.0) + RW2 DNG r-- Panasonic Lumix Raw Format (0.21.2-Release) + RWL DNG r-- Leica Raw Format (0.21.2-Release) + SCR* SCR r-- ZX-Spectrum SCREEN$ + SCT* SCT r-- Scitex HandShake + SFW* SFW r-- Seattle Film Works + SGI* SGI rw+ Irix RGB image + SHTML* HTML -w- Hypertext Markup Language and a client-side image map + SIX* SIXEL rw- DEC SIXEL Graphics Format + SIXEL* SIXEL rw- DEC SIXEL Graphics Format +SPARSE-COLOR* TXT -w+ Sparse Color + SR2 DNG r-- Sony Raw Format 2 (0.21.2-Release) + SRF DNG r-- Sony Raw Format (0.21.2-Release) + SRW DNG r-- Samsung Raw Format (0.21.2-Release) + STEGANO* STEGANO r-- Steganographic image + STI DNG r-- Sinar CaptureShop Raw Format (0.21.2-Release) + STRIMG* STRIMG rw- String to image and back + SUN* SUN rw+ SUN Rasterfile + SVG* SVG rw+ Scalable Vector Graphics (RSVG 2.58.0) + SVGZ* SVG rw+ Compressed Scalable Vector Graphics (RSVG 2.58.0) + TEXT* TXT r-- Text + TGA* TGA rw- Truevision Targa image +THUMBNAIL* THUMBNAIL -w+ EXIF Profile Thumbnail + TIFF* TIFF rw+ Tagged Image File Format (LIBTIFF, Version 4.6.0) + Compression options: None, Fax/Group3, Group4, JBIG, JPEG, LERC, LZW, LZMA, RLE, ZIP, ZSTD, WEBP + TIFF64* TIFF rw+ Tagged Image File Format (64-bit) (LIBTIFF, Version 4.6.0) + Compression options: None, Fax/Group3, Group4, JBIG, JPEG, LERC, LZW, LZMA, RLE, ZIP, ZSTD, WEBP + TILE* TILE r-- Tile image with a texture + TIM* TIM r-- PSX TIM + TM2* TIM2 r-- PS2 TIM2 + TTC* TTF r-- TrueType font collection (Freetype 2.13.2) + TTF* TTF r-- TrueType font (Freetype 2.13.2) + TXT* TXT rw+ Text + UBRL* BRAILLE -w- Unicode Text format + UBRL6* BRAILLE -w- Unicode Text format 6dot + UIL* UIL -w- X-Motif UIL table + UYVY* UYVY rw- 16bit/pixel interleaved YUV + VDA* TGA rw- Truevision Targa image + VICAR* VICAR rw- Video Image Communication And Retrieval + VID* VID rw+ Visual Image Directory + VIFF* VIFF rw+ Khoros Visualization image + VIPS* VIPS rw+ VIPS image + VST* TGA rw- Truevision Targa image + WBMP* WBMP rw- Wireless Bitmap (level 0) image + WEBM VIDEO rw+ Open Web Media + WEBP* WEBP rw+ WebP Image Format (libwebp 1.3.2 [020F]) + WMF* WMF r-- Windows Meta File + WMV VIDEO rw+ Windows Media Video + WMZ* WMF r-- Compressed Windows Meta File + WPG* WPG rw- Word Perfect Graphics + X* X rw+ X Image + X3F DNG r-- Sigma Camera RAW Format (0.21.2-Release) + XBM* XBM rw- X Windows system bitmap (black and white) + XC* XC r-- Constant image uniform color + XCF* XCF r-- GIMP image + XPM* XPM rw- X Windows system pixmap (color) + XPS XPS r-- Microsoft XML Paper Specification + XV* VIFF rw+ Khoros Visualization image + XWD* XWD rw- X Windows system window dump (color) + YAML YAML -w+ The image format and characteristics + YCbCr* YCbCr rw+ Raw Y, Cb, and Cr samples + YCbCrA* YCbCr rw+ Raw Y, Cb, Cr, and alpha samples + YUV* YUV rw- CCIR 601 4:1:1 or 4:2:2 + +* native blob support +r read support +w write support ++ support for multiple images +``` + +Finished scrolling? :p diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..022019b --- /dev/null +++ b/docs/index.md @@ -0,0 +1,5 @@ +# ortfo/db + +ortfo's database management system. + +![](/db/demo.gif) diff --git a/docs/internationalization.md b/docs/internationalization.md new file mode 100644 index 0000000..7889d4f --- /dev/null +++ b/docs/internationalization.md @@ -0,0 +1,67 @@ +# Internationalization + +To share your works with the world, and with your future job, you might want to translate your works' descriptions to multiple languages. ortfo/db has _first-class_ support for this by allowing you to define your works' descriptions in multiple languages. + +## Usage example + +
+
+ +
A work in English on en.ewen.works
+
+ +
+ +
The same work in French at fr.ewen.works
+
+
+ +## Language markers + +Simply add a _language marker_ in your description file on its own line. Everything that you write after this marker, and before the next marker, is considered to be written in that language. + +The markers look like this: + +```md +:: language code +``` + +Note that this โ€œlanguage codeโ€ could technically be anything you want, but it's recommended (and might in the future be required to be) a [BCP 47](https://en.wikipedia.org/wiki/IETF_language_tag#List_of_common_primary_language_subtags) language code. + +### Example + +```md +--- +wip: yes +--- + +# ortfo + +:: en + +A simple way to manage _lots_ of projects for a portfolio website + +:: fr + +Une maniรจre simple de gรฉrer _beaucoup_ de projets pour un site web de portfolio + +:: ja + +็งใฎๆ—ฅๆœฌ่ชžใฏๆ‚ชใ„ใงใ™ใ‹ใ‚‰ใ€็Ÿฅใ‚‰ใชใ„ wwww +``` + +## Untranslated content + +Content that isn't translated is considered to have the special language code `default`. + +All content before any language markers is considered untranslated. + +This is particularly useful for the title of the work, which is usually the same in all languages. + +## In `database.json` + +The database's [Content](/db/database-format.md#content) will be an object mapping every language code used in the description file to the content blocks of the work. + +## `layout` considerations + +Since the [Layout](/db/layouts.md) is shared by all languages, you must have the same number of paragraph, links and media blocks in every language. diff --git a/docs/json-schemas.data.js b/docs/json-schemas.data.js new file mode 100644 index 0000000..7a4e303 --- /dev/null +++ b/docs/json-schemas.data.js @@ -0,0 +1,10 @@ +import { getGoVersion } from "./client-libraries-versions" + +export default { + watch: ["ortfodb/meta.go"], + async load(watchedFiles) { + return { + version: await getGoVersion(watchedFiles[0]), + } + }, +} diff --git a/docs/json-schemas.md b/docs/json-schemas.md new file mode 100644 index 0000000..f207117 --- /dev/null +++ b/docs/json-schemas.md @@ -0,0 +1,93 @@ + + +# JSON Schemas + +ortfo/db exports [JSON Schemas](https://json-schema.org/) for the different data files it uses. + +These schemas serve as both validation when running the program, and as a way to provide a nice [auto-complete experience in your editor](#using-it-in-your-editor), provided that it supports JSON schemas. + +::: tip Client libraries + +Want type definitions in your code? Check out the [client libraries](/db/client-libraries.md) for your language. + +::: + +## Getting the schemas + +### Locally + +See [`ortfodb schemas`](/db/commands/schemas.md) + +### Over the network + +The schemas are all available on ortfo/db's repository in the `schemas/` directory, and are re-exported to the ortfo.org domain for easier access. + +[ortfo.org/configuration.schema.json](https://ortfo.org/configuration.schema.json) +: The schema for the `ortfodb.yaml` [configuration file](/db/configuration.md) + +[ortfo.org/database.schema.json](https://ortfo.org/database.schema.json) +: The schema for the `database.json` file (see [Database format](/db/database-format.md)) + +[ortfo.org/tags.schema.json](https://ortfo.org/tags.schema.json) +: The schema for the [tags repository](/db/tags.md) + +[ortfo.org/technologies.schema.json](https://ortfo.org/technologies.schema.json) +: The schema for the [technologies repository](/db/technologies.md) + +#### Version pining + +Instead of getting the latest version, you can get a specific version by specifying it in the URL before the file name: + +
+https://ortfo.org/{{ version }}/resource name.schema.json +
+ +## Using it in your editor + +A motivating example, for the [tags repository](/db/tags.md) file: + +```yaml +# yaml-language-server: $schema=https://ortfo.org/tags.schema.json + +- singular: website + plural: websites + aliases: site # expected array of strings, got string // [!code error] +``` + +RedHat develops a [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) for YAML that [includes JSON Schema support](https://github.com/redhat-developer/yaml-language-server?tab=readme-ov-file#language-server-settings), so most IDEs that support LSPs should be able to support this feature. + +### On files directly + +You can add a magic comment at the top of your file to associate it with a JSON schema [[docs]](https://github.com/redhat-developer/yaml-language-server?tab=readme-ov-file#using-inlined-schema): + +```yaml{1} +# yaml-language-server: $schema=https://ortfo.org/configuration.schema.json + +make thumbnails: + enabled: true + ... +``` + +### Associating by filename + +You can associate [glob patterns]() of YAML filenames with JSON schemas in your editor settings, [see the documentation](https://github.com/redhat-developer/yaml-language-server?tab=readme-ov-file#associating-a-schema-to-a-glob-pattern-via-yamlschemas) + +## IDE support + +VSCode +: [RedHat YAML Extension](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml) + +Neovim +: [coc-yaml](https://github.com/neoclide/coc-yaml), a [CoC](https://github.com/neoclide/coc.nvim) plugin +: Any LSP client plugin, such as [nvim-lspconfig](https://github.com/neovim/nvim-lspconfig) should also do the trick + +_Other editors_ +: Please contribute to the docs (see "Edit this page" just below) diff --git a/docs/layouts.md b/docs/layouts.md new file mode 100644 index 0000000..a960810 --- /dev/null +++ b/docs/layouts.md @@ -0,0 +1,125 @@ +# Complex layouts + +ortfo/db allows you to declare that some [content blocks](/db/your-first-description-file.md#blocks) are arranged in a more interesting way than just one after the other. + +## Usage example + +
+ +
On ewen.works
+
+ + +## Declaring layouts + +Layouts are declared in the metadata frontmatter of your description file: + +```md{5-7} +--- +started: 2023-04-12 +tags: [web, design, ux, ui] +made with: [figma, react, go] +layouts: + - [p1, m1] + - [l1, l2, l3] +--- + +# 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) + +[Documentation](https://ortfo.org/db) + +[Website using ortfodb](https://net7.dev/realisation.html) +``` + +You declare layouts as a grid. To refer to a content block, you put a letter that specifies the type of block (`p` for paragraphs, `m` for media and `l` for standalone links), and a number that refers to the position of that content block in the file. + +For example, to refer to the second link, you would write `l2`. + +The example above declares the following layout: + +
+ + + + + + + + + + +
This is a paragraph of text. It can contaโ€ฆdemo.mp4
Link to the source codeDocumentationWebsite using ortfodb
+
+ +You can do just about anything that you would think of. + +## In `database.json` + +The advantage of declaring layouts like this in ortfo/db is that your frontend has almost nothing left to do do render the content appropriately. + +The generated database file will contain a two-dimensional array that represents this layout, in a _homogeneous_ way: every row will contain exactly the same number of columns. + +The previous example generates the following in database.json: + +```jsonc +{ + "my-work": { + "content": { + "en": { + "blocks": [...], + "layout": [ // [!code focus] + // id of p1 id of m1 // [!code focus] + [ "1JsYa91YMM", "1JsYa91YMM", "1JsYa91YMM", "GBpC-nYDgw", "GBpC-nYDgw", "GBpC-nYDgw" ], // [!code focus] + // id of l1 id of l2 id of l3 // [!code focus] + [ "TYxPfqjbPR", "TYxPfqjbPR", "ycmt3306Po", "ycmt3306Po", "FD-ZGJKusV", "FD-ZGJKusV" ] // [!code focus] + ], // [!code focus] + ... + } + } + } +} +``` + +### An example: rendering with grid-template-areas + +Here is an example of how you could render this layout using CSS Grid's [`grid-template-areas`](https://developer.mozilla.org/en-US/docs/Web/CSS/grid-template-areas): + +```js +const content = myWorkFromDatabase.content[language]; + +let areasDeclaration = ""; + +for (const row of content.layout) { + let rowDeclaration = ""; + for (const cell of row) { + // need to prefix with an underscore + // because some content block IDs can start with a dash, + // this will be fixed in the future... + rowDeclaration += `_${cell} `; + } + areasDeclaration += `'${rowDeclaration}' `; +} + +// If you prefer, functional-style: +areasDeclaration = content.layout + .map((row) => `'${row.map((id) => `_${id}`).join(" ")}'`) + .join(" "); + +// Assuming container refers to a DOM element +// that contains all of the content blocks +container.style.gridTemplateAreas = areasDeclaration; + +for (const { id } of content.blocks) { + // Assuming each individual content block is + // a DOM element with an id that is + // the same as the content block's id + const block = document.getElementById(id); + block.style.gridArea = `_${id}`; +} +``` diff --git a/docs/markdown.md b/docs/markdown.md new file mode 100644 index 0000000..13c6daa --- /dev/null +++ b/docs/markdown.md @@ -0,0 +1,41 @@ +# Extra markdown features + +ortfo supports a few additional markdown features: + +## Abbreviations + +Syntax +: ```md + *[YAML]: Yet Another Markup Language + ``` + +In `database.json` +: Every occurence of `YAML` in paragraphs will be replaced with `YAML`, directly in the paragraph content[^1] + +[^1]: Paragraph content is in `(work).content.(language).blocks.(block).content`. (See [Database format](/db/database-format.md) for more information on where things are stored in the `database.json`) + +## Footnotes + +Syntax +: `footnote reference[^1]` and then `[^1]: footnote content` + +In `database.json` +: Stored in `(work).content.(language).footnotes` as an object, mapping references to content. In this example, the object would be: + + ```json + { + "1": "footnote content" + } + ``` + +## Smarty pants + +Typographic replacements + +| Write | `--` | `---` | `->` | `<-` | `...` | `<<` | `>>` | +| ----- | ---- | ----- | ---- | ---- | ----- | ---- | ---- | +| Get | โ€“ | โ€” | โ†’ | โ† | โ€ฆ | ยซ | ยป | + +::: tip +Of course, these replacements are not applied in code blocks or `inline code`. +::: diff --git a/docs/scattered-mode.md b/docs/scattered-mode.md new file mode 100644 index 0000000..ad9a277 --- /dev/null +++ b/docs/scattered-mode.md @@ -0,0 +1,69 @@ +--- +prev: false +--- + +# 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 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) + +## Advantages + +It's useful if you want to re-use files that you use in the project itself without having to copy anything over. + +For example, if you're describing a music album, you most media files that you'll include in the description.md file are probably already in the project's folder. In scattered mode, you can just reference them easily with `../`. For example, if you want to reference `ame-to-yuki-final-v7-final-final.flac`[^1] in your description.md file, you can just write `../ame-to-yuki-final-v7-final-final.flac`. + +[^1]: least unhiged music producer file naming scheme + +## Configuration + +You can change the folder name to use something else, instead of `.ortfo`. Just change the `scattered mode folder` setting in your `ortfodb.yaml` configuration file. + +```yaml +... +build metadata file: .lastbuild.yaml +media: + at: media/ +scattered mode folder: .ortfo // [!code focus] +tags: + repository: ... +``` diff --git a/docs/tags.md b/docs/tags.md new file mode 100644 index 0000000..89cf7f7 --- /dev/null +++ b/docs/tags.md @@ -0,0 +1,77 @@ + + +# Tags + +Tags are a way to categorize your different projects. + +## Usage example + +
+ +
Show all works tagged "command-line" on ewen.works
+
+ + +## Declaration + +You can define all valid tags for your works in a central place with a `tags.yaml` file. + +Then, reference the path to that file in your `ortfodb.yaml` configuration file: + +```yaml +... + at: media/ + +technologies: + repository: path/to/technologies.yaml + +tags: // [!code focus] + repository: path/to/tags.yaml// [!code focus] +``` + +### Example + +```yaml +# yaml-language-server: $schema=https://ortfo.org/tags.schema.json + +- singular: automation + plural: automation + +- singular: command-line + plural: command-line + aliases: [cli, command line] + description: Programs that run in the terminal, a text-based interface for computers. + learn more at: https://www.hostinger.com/tutorials/what-is-cli +``` + +::: tip What's that `# yaml-language-server` thing? +See [Declaring JSON Schemas on files](/db/json-schemas.md#on-files-directly) +::: + +### Available properties + + + + + +## Usage + +In your work's description file, refer to tag names by their `plural`, `singular` or any of the `aliases`: + +```md +--- +wip: true +tags: [automation, cli] // [!code focus] +made with: [go, vite] +--- + +# ortfo +``` + +## Enforcing correct tags + +In the future, ortfo/db might enforce that all tags used in your works are defined in the `tags.yaml` file. + +This would prevent typos. diff --git a/docs/technologies.md b/docs/technologies.md new file mode 100644 index 0000000..d17f273 --- /dev/null +++ b/docs/technologies.md @@ -0,0 +1,91 @@ + + +# Technologies + +ortfo/db has a concept of _technologies_. This allows you to specify with what tools the work was made. Note that the term is intended to be very broad-reaching: if you are describing a painting, for example, โ€œoil paintโ€ and โ€œcanvasโ€ would be considered technologies. If you are describing a website, โ€œHTMLโ€ and โ€œCSSโ€ would be considered technologies. + +## Usage example + +
+
+ +
Showing technologies used to make a work on ewen.works
+
+ +
+ +
Showing all works made with Photoshop at ewen.works/using/photoshop
+
+
+ +## Declaration + +You can define all valid technologies for your works in a central place with a `technologies.yaml` file. + +Then, reference the path to that file in your `ortfodb.yaml` configuration file: + +```yaml +... + at: media/ + +technologies: // [!code focus] + repository: path/to/technologies.yaml // [!code focus] + +tags: + repository: path/to/tags.yaml +``` + +The file itself is a list of technologies that have various properties. + +### Example + +```yaml +# yaml-language-server: $schema=https://ortfo.org/technologies.schema.json + +- slug: go + name: Go + by: Google + files: ["*.go"] + learn more at: https://go.dev + description: | + An straightforward low-level open source programming language supported by Google featuring built-in concurrency and a robust standard library + +- slug: vue + name: Vue + aliases: ["vuejs"] + files: ["*.vue"] + autodetect: ["vue in package.json"] + learn more at: https://vuejs.org + description: | + The progressive JavaScript framework +``` + +::: tip What's that `# yaml-language-server` thing? +See [Declaring JSON Schemas on files](/db/json-schemas.md#on-files-directly) +::: + +### Properties + + + +## Usage + +In your work's description file, refer to technologies names by their `slug`, `name` or any of the `aliases`: + +```md +--- +wip: true +tags: [automation, cli] +made with: [go, vue] // [!code focus] +--- + +# ortfo +``` + +## Enforcing correct technologies + +In the future, ortfo/db might enforce that all technologies used in your works are defined in the `technologies.yaml` file. + +This would prevent typos. diff --git a/docs/thumbnails.md b/docs/thumbnails.md new file mode 100644 index 0000000..06dca9b --- /dev/null +++ b/docs/thumbnails.md @@ -0,0 +1,79 @@ +# Thumbnail generation + +ortfo/db's compiler allows you to automatically generate thumbnails for your media files. + +## Configuration + +Configuration of thumbnails generation is done via the `make thumbnails` section of the configuration: + +```yaml{4-12} + enabled: false + file name template: "" + +make thumbnails: + input file: "" + enabled: true + sizes: + - 100 + - 400 + - 600 + - 1200 + file name template: /@.webp + +media: +``` + +### `input file` + +TODO + +### `enabled` + +Controls whether thumbnails are generated or not + +### `sizes` + +Array of sizes to generate thumbnails for. The sizes are in pixels. The generated thumbnail will have its largest side equal to the size specified, while preserving its aspect ratio. + +### `file name template` + +The template for the file name of the generated thumbnails. The following placeholders are available: + +- ``: The work's identifier +- ``: The [block](/db/your-first-description-file.md#blocks)'s identifier +- ``: The size of the thumbnail + + + +## Usage + +Generated thumbnails will be created in the media directory, using the [file name template](#file-name-template) to determine the full filepath. + +The output database.json file will include paths to these files alongside the media blocks: + +```json{12-17} +{ + "ideaseed": { + "content": { + "en": { + "blocks": [ + { + "id": "GBpC-nYDgw", + "type": "media", + "anchor": "ideaseed-logo-black-transparent", + "index": 0, + ... + "thumbnails": { + "100": "ideaseed/GBpC-nYDgw@100.webp", + "400": "ideaseed/GBpC-nYDgw@400.webp", + "600": "ideaseed/GBpC-nYDgw@600.webp", + "1200": "ideaseed/GBpC-nYDgw@1200.webp" + }, + "thumbnailsBuiltAt": "2024-04-14 21:06:29.866092383 +0200 CEST m=+3.902704829", + ... + }, +``` + +## Image formats + +The extension of the file name determines what format the thumbnail will be saved in. As thumbnail generation is handled by [ImageMagick](https://imagemagick.org/index.php), the extension must correspond to one of the [formats supported by ImageMagick](https://imagemagick.org/script/formats.php), [which is _a lot of formats_](./image-formats.md#available-formats). diff --git a/docs/your-first-description-file.md b/docs/your-first-description-file.md new file mode 100644 index 0000000..2129bd7 --- /dev/null +++ b/docs/your-first-description-file.md @@ -0,0 +1,146 @@ +# 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). +::: + +## Creating a `description.md` file quickly with some pre-filled metadata + +You can use the [`ortfodb add`](/db/commands/add) command to quickly create a new description.md file. Some metadata will be pre-determined: for example, the creation date will default to the last git commit's date, if the project you're referencing is a git repository. + +