Skip to content

NIP-54: Switch from Asciidoc to Djot #2180

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
VincenzoImp wants to merge 1 commit into
base: master
Choose a base branch
from
Open

NIP-54: Switch from Asciidoc to Djot #2180

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
100 changes: 63 additions & 37 deletions 54.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,17 +43,33 @@ For example:

## Content

The `content` should be Asciidoc with two extra functionalities: **wikilinks** and **nostr:...** links.
The `content` should be [Djot](https://djot.net/) with two special functionalities:

Unlike normal Asciidoc links `http://example.com[]` that link to external webpages, wikilinks `[[]]` link to other articles in the wiki. In this case, the wiki is the entirety of Nostr. Clicking on a wikilink should cause the client to ask relays for events with `d` tags equal to the target of that wikilink.
1. Links can have target URIs in [NIP-21](21.md) format, like `[Bob](nostr:npub1...)`.
2. When a reference can't be found for a reference-style link, it should link to the wiki article with that name instead (wikilink behavior). The target is normalized following the `d` tag normalization rules above.

Wikilinks can take these forms:
For example:

```djot
Bitcoin is a [cryptocurrency][] invented by [Satoshi Nakamoto][].

See also: [proof of work][] and [lightning network][Lightning Network].

[Satoshi Nakamoto]: nostr:npub1satoshi...
```

1. `[[Target Page]]` -- links to `target-page` and displays as `Target Page`;
2. `[[target page|see this]]` -- links to `target-page` but displays as `see this`;
3. `[[日本語 Topic|Japanese Topic]]` -- links to `日本語-topic` and displays as `Japanese Topic`.
In the article above:
- `[cryptocurrency][]` links to the wiki article with `d` tag `"cryptocurrency"` (no reference defined, so it becomes a wikilink)
- `[Satoshi Nakamoto][]` links to the npub (reference is defined)
- `[proof of work][]` links to the article with `d` tag `"proof-of-work"`
- `[lightning network][Lightning Network]` links to `"lightning-network"`, displays as "lightning network"

`nostr:...` links, as per [NIP-21](21.md), should link to profiles or arbitrary Nostr events. Although it is not recommended to link to specific versions of articles -- instead the _wikilink_ syntax should be preferred, since it should be left to the reader and their client to decide what version of any given article they want to read.
Wikilinks also work with non-Latin scripts following the same normalization rules:
- `[ビットコイン][]` → links to article with `d` tag `"ビットコイン"`
- `[Japanese Article][日本語 記事]` → links to `"日本語-記事"`, displays as "Japanese Article"
- `[Биткойн][]` → links to article with `d` tag `"биткойн"` (Cyrillic, lowercased)

[NIP-21](21.md) `nostr:` links can also be used to link to profiles or arbitrary Nostr events. It is not recommended to link to specific versions of articles — the wikilink syntax should be preferred instead, since it should be left to the reader and their client to decide what version of any given article they want to read.

## Optional extra tags

Expand All @@ -65,13 +81,40 @@ Wikilinks can take these forms:

Event `kind:818` represents a request to merge from a forked article into the source. It is directed to a pubkey and references the original article and the modified event.

[INSERT EVENT EXAMPLE]
```json
{
"content": "I added information about the block size limit",
"kind": 818,
"tags": [
["a", "30818:<destination-pubkey>:bitcoin", "<relay-url>"],
["e", "<version-against-which-the-modification-was-made>", "<relay-url>"],
["p", "<destination-pubkey>"],
["e", "<version-to-be-merged>", "<relay-url>", "source"]
]
}
```

- `.content`: an optional explanation detailing why this merge is being requested.
- `a` tag: tag of the article which should be modified (i.e. the target of this merge request).
- `e` tag: optional version of the article on which this modification is based.
- `e` tag with `source` marker: the ID of the event that should be merged. This event id MUST be of a `kind:30818` as defined in this NIP.

The destination pubkey can create [NIP-25](25.md) reactions that tag the `kind:818` event with `+` or `-` to accept or reject the merge request.

## Redirects

Event `kind:30819` is also defined to stand for "wiki redirects", i.e. if one thinks `Shell structure` should redirect to `Thin-shell structure` they can issue one of these events instead of replicating the content. These events can be used for automatically redirecting between articles on a client, but also for generating crowdsourced "disambiguation" pages ([common in Wikipedia](https://en.wikipedia.org/wiki/Help:Disambiguation)).
Event `kind:30819` is also defined to stand for "wiki redirects", i.e. if one thinks "BTC" should redirect to "Bitcoin" they can issue one of these events instead of replicating the content. These events can be used for automatically redirecting between articles on a client, but also for generating crowdsourced "disambiguation" pages ([common in Wikipedia](https://en.wikipedia.org/wiki/Help:Disambiguation)).

[INSERT EVENT EXAMPLE]
```json
{
"kind": 30819,
"tags": [
["d", "btc"],
["a", "30818:<pubkey>:bitcoin", "<relay-url>"]
],
"content": ""
}
```

## How to decide what article to display

Expand All @@ -94,40 +137,23 @@ As there could be many articles for each given name, some kind of prioritization
[NIP-51](51.md) lists can also be used to create a list of users that are trusted only in the context of wiki authorship or wiki curationship.

## Forks

Wiki-events can tag other wiki-events with a `fork` marker to specify that this event came from a different version. Both `a` and `e` tags SHOULD be used and have the `fork` marker applied, to identify the exact version it was forked from.

## Deference

Wiki-events can tag other wiki-events with a `defer` marker to indicate that it considers someone else's entry as a "better" version of itself. If using a `defer` marker both `a` and `e` tags SHOULD be used.

This is a stronger signal of trust than a `+` reaction.

This marker is useful when a user edits someone else's entry; if the original author includes the editor's changes and the editor doesn't want to keep/maintain an independent version, the `link` tag could effectively be a considered a "deletion" of the editor's version and putting that pubkey's WoT weight behind the original author's version.

## Why Asciidoc?

Wikitext is [garbage](nostr:nevent1qqsqt0gcggry60n72uglhuhypdlmr2dm6swjj69jex5v530gcpazlzsprpmhxue69uhhyetvv9ujumn0wdmksetjv5hxxmmdqy28wumn8ghj7un9d3shjtnyv9kh2uewd9hsygpm7rrrljungc6q0tuh5hj7ue863q73qlheu4vywtzwhx42a7j9n5ueneex) and Markdown is not powerful enough (besides being too freeform and unspecified and prone to generate incompatibilities in the future).

Asciidoc has a strict spec, multiple implementations in many languages, and support for features that are very much necessary in a wiki article, like _sidebars_, _tables_ (with rich markup inside cells), many levels of _headings_, _footnotes_, _superscript_ and _subscript_ markup and _description lists_. It is also arguably easier to read in its plaintext format than Markdown (and certainly much better than Wikitext).
This marker is useful when a user edits someone else's entry; if the original author includes the editor's changes and the editor doesn't want to keep/maintain an independent version, the `defer` tag could effectively be considered a "deletion" of the editor's version and putting that pubkey's WoT weight behind the original author's version.

## Appendix 1: Merge requests
Users can request other users to get their entries merged into someone else's entry by creating a `kind:818` event.

```json
{
"content": "I added information about how to make hot ice-creams",
"kind": 818,
"tags": [
[ "a", "30818:<destination-pubkey>:hot-ice-creams", "<relay-url>" ],
[ "e", "<version-against-which-the-modification-was-made>", "<relay-url>" ],
[ "p", "<destination-pubkey>" ],
[ "e", "<version-to-be-merged>", "<relay-url>", "source" ]
]
}
```
## Why Djot?

`.content`: an optional explanation detailing why this merge is being requested.
`a` tag: tag of the article which should be modified (i.e. the target of this merge request).
`e` tag: optional version of the article in which this modifications is based
`e` tag with `source` marker: the ID of the event that should be merged. This event id MUST be of a `kind:30818` as defined in this NIP.
[Djot](https://djot.net/) is a markup language created by John MacFarlane (author of Pandoc and co-author of CommonMark). It was chosen for the following reasons:

The destination-pubkey is the pubkey being requested to merge something into their article can create [[NIP-25]] reactions that tag the `kind:818` event with `+` or `-`
- **Well-defined spec**: Unlike Markdown (many incompatible dialects) or Asciidoc (spec tied to Ruby implementation), Djot has a clear, standalone specification.
- **Native implementations**: Available in JavaScript, Lua, Rust, Go, and other languages without transpilation.
- **Rich features**: Supports superscript, subscript, footnotes, tables, definition lists, and math — features useful for encyclopedic content.
- **Familiar syntax**: Similar to basic Markdown, making it easy to learn.
- **Fast parsing**: Designed for efficient linear-time parsing.