Wikis: Markdown pages as an Oxygen repository of their own 66fd9d6b1452

//! Wiki pages on the web (hub spec §6.11, oxygenhub#104): view, edit,

//! history, the page list with search, and raw files for images.

use super::{filters, lookup, lookup_role, Error, Page, RepoShell, Shell};

use crate::auth::{Access, Viewer};

use crate::db::accounts;

use crate::repos::view::ChangeView;

use crate::wiki;

use crate::Shared;

use askama::Template;

use axum::extract::{Path, Query, State};

use axum::response::{IntoResponse, Redirect, Response};

use axum::Form;

use serde::Deserialize;

#[derive(Template)]

#[template(path = "wiki.html")]

pub struct WikiPage {

    shell: Shell,

    repo: RepoShell,

    slug: String,

    title: String,

    /// Rendered Markdown, or `None` when there is no such page.

    html: Option<String>,

    sidebar: Option<String>,

    /// Whether the wiki has any page at all.

    any: bool,

    can_edit: bool,

    last: Option<ChangeView>,

    notice: Option<String>,

}

#[derive(Template)]

#[template(path = "wiki_edit.html")]

pub struct WikiEditPage {

    shell: Shell,

    repo: RepoShell,

    slug: String,

    title: String,

    content: String,

    /// Whether the page exists (an edit) or is new.

    exists: bool,

    error: Option<String>,

}

#[derive(Template)]

#[template(path = "wiki_pages.html")]

pub struct WikiPagesPage {

    shell: Shell,

    repo: RepoShell,

    pages: Vec<String>,

    q: String,

    hits: Vec<(String, String)>,

    can_edit: bool,

}

#[derive(Template)]

#[template(path = "wiki_history.html")]

pub struct WikiHistoryPage {

    shell: Shell,

    repo: RepoShell,

    slug: String,

    title: String,

    entries: Vec<ChangeView>,

}

fn base(owner: &str, name: &str) -> String {

    format!("/{owner}/{name}/wiki/")

}

fn render(owner: &str, name: &str, text: &str) -> String {

    crate::render::markdown::render(text, &base(owner, name), &format!("/{owner}/{name}/wiki/_raw/"))

}

/// Whether the viewer may change the wiki: a writer, and not archived.

fn editable(row: &crate::db::repos::RepoRow, rs: &RepoShell) -> bool {

    rs.can(Access::Write) && !row.archived

}

#[derive(Deserialize)]

pub struct ShowQuery {

    notice: Option<String>,

}

/// `GET /{owner}/{name}/wiki`: the Home page.

pub async fn home(

    State(app): State<Shared>,

    viewer: Viewer,

    Path((owner, name)): Path<(String, String)>,

    Query(q): Query<ShowQuery>,

) -> Result<Page<WikiPage>, Error> {

    show_page(app, viewer, owner, name, wiki::HOME.into(), q.notice).await

}

/// `GET /{owner}/{name}/wiki/{slug}`.

pub async fn show(

    State(app): State<Shared>,

    viewer: Viewer,

    Path((owner, name, slug)): Path<(String, String, String)>,

    Query(q): Query<ShowQuery>,

) -> Result<Page<WikiPage>, Error> {

    show_page(app, viewer, owner, name, slug, q.notice).await

}

async fn show_page(

    app: Shared,

    viewer: Viewer,

    owner: String,

    name: String,

    slug: String,

    notice: Option<String>,

) -> Result<Page<WikiPage>, Error> {

    let shell = Shell::new(&app, &format!("/{owner}/{name}/wiki/{slug}"), &viewer);

    let (repo, row, role) = lookup(&app, &shell, &viewer, &owner, &name).await?;

    if !wiki::slug_ok(&slug) {

        return Err(Error::not_found(shell));

    }

    let e = |e| Error::from_repo(shell.clone(), e);

    let text = wiki::page(&app, &repo, &slug).await.map_err(e)?;

    let sidebar = wiki::page(&app, &repo, wiki::SIDEBAR).await.map_err(e)?;

    let any = !wiki::pages(&app, &repo).await.map_err(e)?.is_empty();

    let last = if text.is_some() { wiki::history(&app, &repo, &slug, 1).await.map_err(e)?.into_iter().next() } else { None };

    let rs = RepoShell::new(&app, &row, "wiki").with_role(role);

    let can_edit = editable(&row, &rs);

    Ok(Page(WikiPage {

        html: text.as_deref().map(|t| render(&owner, &name, t)),

        sidebar: sidebar.as_deref().map(|t| render(&owner, &name, t)),

        title: wiki::title_of(&slug),

        shell,

        repo: rs,

        slug,

        any,

        can_edit,

        last,

        notice,

    }))

}

#[derive(Deserialize)]

pub struct PagesQuery {

    #[serde(default)]

    q: String,

}

/// `GET /{owner}/{name}/wiki/_pages`: every page, and a search.

pub async fn pages(

    State(app): State<Shared>,

    viewer: Viewer,

    Path((owner, name)): Path<(String, String)>,

    Query(q): Query<PagesQuery>,

) -> Result<Page<WikiPagesPage>, Error> {

    let shell = Shell::new(&app, &format!("/{owner}/{name}/wiki/_pages"), &viewer);

    let (repo, row, role) = lookup(&app, &shell, &viewer, &owner, &name).await?;

    let e = |e| Error::from_repo(shell.clone(), e);

    let pages = wiki::pages(&app, &repo).await.map_err(e)?;

    let q: String = q.q.trim().chars().take(100).collect();

    let hits = if q.is_empty() { vec![] } else { wiki::search(&app, &repo, &q).await.map_err(e)? };

    let rs = RepoShell::new(&app, &row, "wiki").with_role(role);

    let can_edit = editable(&row, &rs);

    Ok(Page(WikiPagesPage { shell, repo: rs, pages, q, hits, can_edit }))

}

/// `GET /{owner}/{name}/wiki/{slug}/history`.

pub async fn history(

    State(app): State<Shared>,

    viewer: Viewer,

    Path((owner, name, slug)): Path<(String, String, String)>,

) -> Result<Page<WikiHistoryPage>, Error> {

    let shell = Shell::new(&app, &format!("/{owner}/{name}/wiki/{slug}/history"), &viewer);

    let (repo, row, role) = lookup(&app, &shell, &viewer, &owner, &name).await?;

    if !wiki::slug_ok(&slug) {

        return Err(Error::not_found(shell));

    }

    let mut entries = wiki::history(&app, &repo, &slug, 100).await.map_err(|e| Error::from_repo(shell.clone(), e))?;

    super::attribute(&app, &mut entries.iter_mut().collect::<Vec<_>>()).await;

    Ok(Page(WikiHistoryPage {

        title: wiki::title_of(&slug),

        shell,

        repo: RepoShell::new(&app, &row, "wiki").with_role(role),

        slug,

        entries,

    }))

}

#[derive(Deserialize)]

pub struct NewQuery {

    #[serde(default)]

    title: String,

}

/// `GET /{owner}/{name}/wiki/_new`: a new page, named by the form.

pub async fn new_form(

    State(app): State<Shared>,

    viewer: Viewer,

    Path((owner, name)): Path<(String, String)>,

    Query(q): Query<NewQuery>,

) -> Result<Page<WikiEditPage>, Error> {

    let shell = Shell::new(&app, &format!("/{owner}/{name}/wiki/_new"), &viewer);

    let (_, row, role) = lookup_role(&app, &shell, &viewer, &owner, &name, Access::Write).await?;

    let slug = wiki::slug_of(&q.title);

    Ok(Page(WikiEditPage {

        title: if slug.is_empty() { String::new() } else { wiki::title_of(&slug) },

        shell,

        repo: RepoShell::new(&app, &row, "wiki").with_role(role),

        slug,

        content: String::new(),

        exists: false,

        error: None,

    }))

}

/// `GET /{owner}/{name}/wiki/{slug}/edit`.

pub async fn edit_form(

    State(app): State<Shared>,

    viewer: Viewer,

    Path((owner, name, slug)): Path<(String, String, String)>,

) -> Result<Page<WikiEditPage>, Error> {

    let shell = Shell::new(&app, &format!("/{owner}/{name}/wiki/{slug}/edit"), &viewer);

    let (repo, row, role) = lookup_role(&app, &shell, &viewer, &owner, &name, Access::Write).await?;

    if !wiki::slug_ok(&slug) {

        return Err(Error::not_found(shell));

    }

    let text = wiki::page(&app, &repo, &slug).await.map_err(|e| Error::from_repo(shell.clone(), e))?;

    Ok(Page(WikiEditPage {

        title: wiki::title_of(&slug),

        shell,

        repo: RepoShell::new(&app, &row, "wiki").with_role(role),

        slug,

        exists: text.is_some(),

        content: text.unwrap_or_default(),

        error: None,

    }))

}

#[derive(Deserialize)]

pub struct SaveForm {

    #[serde(rename = "_csrf")]

    csrf_token: String,

    /// The page's title; its slug is the file name. A changed title on an

    /// existing page renames it.

    #[serde(default)]

    title: String,

    #[serde(default)]

    content: String,

    #[serde(default)]

    message: String,

}

/// `POST /{owner}/{name}/wiki/{slug}/edit` (`_new` for a new page): the

/// change is authored by the user and signed by the hub as their delegate.

pub async fn save(

    State(app): State<Shared>,

    viewer: Viewer,

    Path((owner, name, slug)): Path<(String, String, String)>,

    Form(f): Form<SaveForm>,

) -> Result<Response, Error> {

    let shell = Shell::new(&app, &format!("/{owner}/{name}/wiki/{slug}/edit"), &viewer);

    let me = super::settings::require(&viewer, &shell)?;

    super::settings::csrf(&viewer, &f.csrf_token, &shell)?;

    let (repo, row, role) = lookup_role(&app, &shell, &viewer, &owner, &name, Access::Write).await?;

    let is_new = slug == "_new";

    let old_slug = if is_new { String::new() } else { slug.clone() };

    let new_slug = wiki::slug_of(&f.title);

    let content = f.content.replace("\r\n", "\n");

    let again = |msg: String| {

        Page(WikiEditPage {

            title: f.title.clone(),

            shell: shell.clone(),

            repo: RepoShell::new(&app, &row, "wiki").with_role(role),

            slug: if is_new { new_slug.clone() } else { old_slug.clone() },

            content: content.clone(),

            exists: !is_new,

            error: Some(msg),

        })

        .into_response()

    };

    if !is_new && !wiki::slug_ok(&old_slug) {

        return Err(Error::not_found(shell));

    }

    if !wiki::slug_ok(&new_slug) {

        return Ok(again("A page title is letters, digits, spaces, dots, dashes and underscores, up to 100 characters.".into()));

    }

    if content.trim().is_empty() {

        return Ok(again("Write something on the page.".into()));

    }

    let signer = match super::edit::signer_for(&app, me.account.id).await {

        Ok(s) => s,

        Err(msg) => return Ok(again(msg)),

    };

    let renamed = !is_new && new_slug != old_slug;

    let taken = wiki::page(&app, &repo, &new_slug).await.map_err(|e| Error::from_repo(shell.clone(), e))?.is_some();

    if (is_new || renamed) && taken {

        return Ok(again(format!("There is already a page called {}.", wiki::title_of(&new_slug))));

    }

    let message = if f.message.trim().is_empty() {

        format!(

            "{} {}",

            if is_new {

                "Create"

            } else if renamed {

                "Rename and update"

            } else {

                "Update"

            },

            wiki::title_of(&new_slug)

        )

    } else {

        f.message.trim().chars().take(200).collect()

    };

    let mut edits = vec![];

    if renamed {

        edits.push(oxy_core::repo::FileEdit { path: wiki::path_of(&old_slug), content: None });

    }

    edits.push(oxy_core::repo::FileEdit { path: wiki::path_of(&new_slug), content: Some(content.clone().into_bytes()) });

    if let Err(e) = wiki::commit(&app, &repo, edits, message.clone(), signer).await {

        return Ok(again(e.to_string()));

    }

    accounts::audit(&app.db, Some(&me.account), "wiki.edited", &repo.to_string(), &new_slug).await.ok();

    crate::hooks::emit(&app, &row, "wiki", &me.account.username, serde_json::json!({ "page": new_slug, "message": message })).await;

    Ok(Redirect::to(&format!("/{owner}/{name}/wiki/{new_slug}")).into_response())

}

#[derive(Deserialize)]

pub struct DeleteForm {

    #[serde(rename = "_csrf")]

    csrf_token: String,

}

/// `POST /{owner}/{name}/wiki/{slug}/delete`: a change that removes the page.

pub async fn delete(

    State(app): State<Shared>,

    viewer: Viewer,

    Path((owner, name, slug)): Path<(String, String, String)>,

    Form(f): Form<DeleteForm>,

) -> Result<Response, Error> {

    let shell = Shell::new(&app, &format!("/{owner}/{name}/wiki/{slug}"), &viewer);

    let me = super::settings::require(&viewer, &shell)?;

    super::settings::csrf(&viewer, &f.csrf_token, &shell)?;

    let (repo, row, _) = lookup_role(&app, &shell, &viewer, &owner, &name, Access::Write).await?;

    if !wiki::slug_ok(&slug) || wiki::page(&app, &repo, &slug).await.map_err(|e| Error::from_repo(shell.clone(), e))?.is_none() {

        return Err(Error::not_found(shell));

    }

    let signer = super::edit::signer_for(&app, me.account.id).await.map_err(|m| Error::bad(shell.clone(), m))?;

    let message = format!("Delete {}", wiki::title_of(&slug));

    wiki::commit(&app, &repo, vec![oxy_core::repo::FileEdit { path: wiki::path_of(&slug), content: None }], message.clone(), signer)

        .await

        .map_err(|e| Error::from_repo(shell.clone(), e))?;

    accounts::audit(&app.db, Some(&me.account), "wiki.deleted", &repo.to_string(), &slug).await.ok();

    crate::hooks::emit(&app, &row, "wiki", &me.account.username, serde_json::json!({ "page": slug, "message": message, "deleted": true }))

        .await;

    Ok(Redirect::to(&format!("/{owner}/{name}/wiki?notice={}", super::settings::urlencode(&format!("{} deleted.", wiki::title_of(&slug)))))

        .into_response())

}

/// `GET /{owner}/{name}/wiki/_raw/{*path}`: a file of the wiki as bytes,

/// for images pages embed.

pub async fn raw(

    State(app): State<Shared>,

    viewer: Viewer,

    Path((owner, name, path)): Path<(String, String, String)>,

) -> Result<Response, Error> {

    let shell = Shell::new(&app, &format!("/{owner}/{name}/wiki/_raw/{path}"), &viewer);

    let (repo, _, _) = lookup(&app, &shell, &viewer, &owner, &name).await?;

    if !wiki::exists(&app, &repo) || path.contains("..") {

        return Err(Error::not_found(shell));

    }

    let p = path.trim_matches('/').to_string();

    let file_name = p.rsplit('/').next().unwrap_or("").to_string();

    let bytes = app

        .wikis

        .read(&repo, move |r, _| {

            let heads = r.bookmarks()?.into_iter().find(|b| b.name == wiki::BOOKMARK).map(|b| b.heads).unwrap_or_default();

            Ok(r.file_at(&p, Some(&heads)).ok())

        })

        .await

        .map_err(|e| Error::from_repo(shell.clone(), e))?

        .ok_or_else(|| Error::not_found(shell.clone()))?;

    Ok(super::raw(bytes, &file_name, true))

}

//! Wikis (hub spec §6.11, oxygenhub#104): Markdown pages kept as an

//! Oxygen repository of their own beside the code, under

//! `<data>/wikis/<owner>/<name>`, read and written on the web and cloned

//! or pushed as `OWNER/NAME.wiki`. A page `Getting-Started` is the file

//! `Getting-Started.md` on bookmark `main`; `_Sidebar.md` is the sidebar.

//! Web edits are changes authored by the user and signed by the hub as

//! their delegate, exactly as code edits are (§6.9).

use crate::repos::edits::{Committed, Signer};

use crate::repos::view::{self, ChangeView};

use crate::repos::{RepoError, RepoName};

use crate::Shared;

use oxy_core::hash::ChangeHash;

use oxy_core::identity::Domain;

use oxy_core::repo::{FileEdit, Repo};

pub const BOOKMARK: &str = "main";

pub const HOME: &str = "Home";

pub const SIDEBAR: &str = "_Sidebar";

/// The suffix a wiki's clone address carries: `OWNER/NAME.wiki`.

pub const SUFFIX: &str = ".wiki";

/// Pages searched at most.

const MAX_SEARCHED: usize = 500;

/// A page's name in a URL and file name: `Getting-Started`.

pub fn slug_ok(slug: &str) -> bool {

    !slug.is_empty()

        && slug.len() <= 100

        && slug.chars().all(|c| c.is_ascii_alphanumeric() || matches!(c, '-' | '_' | '.'))

        && !slug.contains("..")

        && !slug.starts_with('.')

        && !slug.ends_with('.')

}

/// `Getting Started` → `Getting-Started`.

pub fn slug_of(title: &str) -> String {

    title.split_whitespace().collect::<Vec<_>>().join("-")

}

/// `Getting-Started` → `Getting Started`.

pub fn title_of(slug: &str) -> String {

    slug.replace('-', " ")

}

pub fn path_of(slug: &str) -> String {

    format!("{slug}.md")

}

/// The page a file at the root is, if it is one.

pub fn slug_from_path(path: &str) -> Option<&str> {

    path.strip_suffix(".md").filter(|s| !s.contains('/') && slug_ok(s))

}

/// `OWNER/NAME.wiki` → the repository it belongs to, and whether it was

/// a wiki address at all.

pub fn parent_of(name: &RepoName) -> (RepoName, bool) {

    match name.name.strip_suffix(SUFFIX).and_then(|n| RepoName::new(&name.owner, n)) {

        Some(parent) => (parent, true),

        None => (name.clone(), false),

    }

}

pub fn exists(app: &Shared, repo: &RepoName) -> bool {

    app.wikis.exists(repo)

}

/// `main`'s heads, empty before the first page.

fn heads(r: &Repo) -> Result<Vec<ChangeHash>, RepoError> {

    Ok(r.bookmarks()?.into_iter().find(|b| b.name == BOOKMARK).map(|b| b.heads).unwrap_or_default())

}

/// A page's Markdown, `None` when there is no such page.

pub async fn page(app: &Shared, repo: &RepoName, slug: &str) -> Result<Option<String>, RepoError> {

    if !exists(app, repo) {

        return Ok(None);

    }

    let path = path_of(slug);

    app.wikis

        .read(repo, move |r, _| {

            let heads = heads(r)?;

            if heads.is_empty() {

                return Ok(None);

            }

            Ok(r.file_at(&path, Some(&heads)).ok().map(|b| String::from_utf8_lossy(&b).into_owned()))

        })

        .await

}

/// Every page, by slug, sorted; the sidebar and other `_` pages left out.

pub async fn pages(app: &Shared, repo: &RepoName) -> Result<Vec<String>, RepoError> {

    if !exists(app, repo) {

        return Ok(vec![]);

    }

    app.wikis

        .read(repo, |r, cache| {

            let heads = heads(r)?;

            if heads.is_empty() {

                return Ok(vec![]);

            }

            let loaded = cache.load(r, &heads)?;

            let mut out: Vec<String> =

                loaded.snapshot.files.keys().filter_map(|p| slug_from_path(p)).filter(|s| !s.starts_with('_')).map(String::from).collect();

            out.sort_by_key(|s| s.to_lowercase());

            Ok(out)

        })

        .await

}

/// Pages whose text holds `q`, with a line that does: (slug, snippet).

pub async fn search(app: &Shared, repo: &RepoName, q: &str) -> Result<Vec<(String, String)>, RepoError> {

    let q = q.trim().to_lowercase();

    if q.is_empty() || !exists(app, repo) {

        return Ok(vec![]);

    }

    app.wikis

        .read(repo, move |r, cache| {

            let heads = heads(r)?;

            if heads.is_empty() {

                return Ok(vec![]);

            }

            let loaded = cache.load(r, &heads)?;

            let mut out = vec![];

            for path in loaded.snapshot.files.keys().take(MAX_SEARCHED) {

                let Some(slug) = slug_from_path(path) else { continue };

                let Ok(bytes) = r.file_at(path, Some(&heads)) else { continue };

                let text = String::from_utf8_lossy(&bytes);

                let hit = slug.to_lowercase().contains(&q) || text.to_lowercase().contains(&q);

                if hit {

                    let line = text.lines().find(|l| l.to_lowercase().contains(&q)).unwrap_or("").trim();

                    out.push((slug.to_string(), line.chars().take(160).collect()));

                }

            }

            Ok(out)

        })

        .await

}

/// The changes that touched a page, newest first.

pub async fn history(app: &Shared, repo: &RepoName, slug: &str, limit: usize) -> Result<Vec<ChangeView>, RepoError> {

    if !exists(app, repo) {

        return Ok(vec![]);

    }

    let path = path_of(slug);

    app.wikis

        .read(repo, move |r, cache| {

            if heads(r)?.is_empty() {

                return Ok(vec![]);

            }

            let target = view::resolve(r, cache, BOOKMARK)?;

            Ok(view::history(r, cache, target, Some(&path), 0, limit)?.entries)

        })

        .await

}

/// Record `edits` as a change on the wiki's `main`, authored by the user

/// and signed by the hub as their delegate; the wiki is made on the first.

pub async fn commit(app: &Shared, repo: &RepoName, edits: Vec<FileEdit>, message: String, signer: Signer) -> Result<Committed, RepoError> {

    if !exists(app, repo) {

        // Bound to an id from the start, so it clones before any push.

        app.wikis.create(repo, Some(rand::random::<[u8; 16]>()))?;

    }

    app.wikis

        .write(repo, move |r, _| {

            let base_heads = heads(r)?;

            let author = signer.author.hash();

            let change = r.build_change(&base_heads, &edits, &message, author)?;

            let hash = change.hash();

            let sig = signer.hub_secret.sign(Domain::Change, &signer.hub_key, &hash);

            let mut state = r.load_state(&base_heads)?;

            state.add(change.clone()).map_err(|e| RepoError::Oxy(oxy_core::repo::RepoError::Msg(e.to_string())))?;

            let mut candidates = base_heads.clone();

            candidates.push(hash);

            let heads = state.maximal(&candidates);

            let update = r.host_ref_update(BOOKMARK, &heads, Some((&signer.hub_key, &signer.hub_secret)))?;

            let (old_state, new_state) = (update.old_state.to_hex(), update.new_state.to_hex());

            let report = r.apply_hosted(Some((change, vec![sig])), &[signer.hub_identity.clone(), signer.author.clone()], update)?;

            if let Some(refused) = report.results.iter().find(|x| !x.ok) {

                return Err(RepoError::Oxy(oxy_core::repo::RepoError::Msg(format!("the wiki refused the change: {}", refused.reason))));

            }

            Ok(Committed { change: hash, bookmark: BOOKMARK.into(), old_state, new_state, heads, report })

        })

        .await

}

/// Remove the wiki (to the trash), when the repository goes or an admin

/// asks under Settings › Advanced.

pub fn trash(app: &Shared, repo: &RepoName) -> Result<(), RepoError> {

    if exists(app, repo) {

        app.wikis.trash(repo)?;

    }

    Ok(())

}

#[cfg(test)]

mod tests {

    use super::*;

    #[test]

    fn slugs_titles_and_paths() {

        assert_eq!(slug_of("  Getting   Started "), "Getting-Started");

        assert_eq!(title_of("Getting-Started"), "Getting Started");

        assert_eq!(path_of("Home"), "Home.md");

        assert_eq!(slug_from_path("Home.md"), Some("Home"));

        assert_eq!(slug_from_path("docs/Home.md"), None);

        assert_eq!(slug_from_path("notes.txt"), None);

        assert!(slug_ok("_Sidebar") && slug_ok("v1.2-notes") && !slug_ok("") && !slug_ok("a/b") && !slug_ok("..") && !slug_ok("a b"));

    }

}

{% extends "base.html" %}

{% import "repo_tabs.html" as m %}

{% block title %}{{ title }} · wiki · {{ repo.owner }}/{{ repo.name }}{% endblock %}

{% block bodyattrs %} data-repo="{{ repo.url }}"{% endblock %}

{% block tabs %}{% call m::tabs(repo, "wiki") %}{% endblock %}

{% block content %}

{% if let Some(n) = notice %}<p class="note">{{ n }}</p>{% endif %}

<div class="side-layout wiki">

<div>

  <div class="head"><h1>{{ title }}</h1>

    <p class="small">{% if can_edit %}{% if html.is_some() %}<a class="go" href="{{ repo.url }}/wiki/{{ slug }}/edit">Edit</a> {% endif %}<a class="go" href="{{ repo.url }}/wiki/_new">New page</a> {% endif %}<a class="go" href="{{ repo.url }}/wiki/_pages">Pages</a>{% if html.is_some() %} <a class="go" href="{{ repo.url }}/wiki/{{ slug }}/history">History</a>{% endif %}</p>

  </div>

  {% if let Some(h) = html %}

  <article class="doc wiki-doc">{{ h|safe }}</article>

  {% if let Some(c) = last %}<p class="small mute">Last changed by {{ c.author.name }}{% if let Some(v) = c.via %} via {{ v.name }}{% endif %} <time title="{{ c.when_ms|when_i }}">{{ c.when_ms|ago_i }}</time>{% if can_edit %} · <form class="tiny inline" method="post" action="{{ repo.url }}/wiki/{{ slug }}/delete" onsubmit="return confirm('Delete the page {{ title }}?')"><input type="hidden" name="_csrf" value="{{ shell.csrf }}"><button class="linkish">delete this page</button></form>{% endif %}</p>{% endif %}

  {% else if any %}

  <p class="empty">There is no page called <strong>{{ title }}</strong> yet.{% if can_edit %} <a href="{{ repo.url }}/wiki/_new?title={{ title }}">Create it</a>.{% endif %}</p>

  {% else %}

  <section class="panel">

    <h2>No wiki yet</h2>

    <p>A wiki is Markdown pages kept as an Oxygen repository of their own beside the code: every edit is a signed change, and it clones and pushes like any repository.</p>

    {% if can_edit %}<p><a class="go" href="{{ repo.url }}/wiki/_new?title=Home">Write the first page</a></p>{% endif %}

    <pre class="snippet">oxy clone {{ shell.base_url }}/{{ repo.owner }}/{{ repo.name }}.wiki</pre>

    <p class="small mute">Pages are <code>Name.md</code> at the root on <code>main</code>; <code>_Sidebar.md</code> is the sidebar. Web edits need a delegation to this hub's key, as code edits do.</p>

  </section>

  {% endif %}

</div>

<aside class="side">

  {% if let Some(s) = sidebar %}<section class="side-sec"><div class="doc wiki-side">{{ s|safe }}</div></section>{% endif %}

  <section class="side-sec"><div class="side-head"><h3>Clone this wiki</h3></div><pre class="snippet small">oxy clone {{ shell.base_url }}/{{ repo.owner }}/{{ repo.name }}.wiki</pre></section>

</aside>

</div>

{% endblock %}

{% extends "base.html" %}

{% import "repo_tabs.html" as m %}

{% block title %}{% if exists %}Edit {{ title }}{% else %}New page{% endif %} · wiki · {{ repo.owner }}/{{ repo.name }}{% endblock %}

{% block tabs %}{% call m::tabs(repo, "wiki") %}{% endblock %}

{% block mainclass %} class="wide"{% endblock %}

{% block content %}

<div class="head"><h1>{% if exists %}Edit {{ title }}{% else %}New wiki page{% endif %}</h1></div>

{% if let Some(e) = error %}<p class="error">{{ e }}</p>{% endif %}

<form class="card wide" method="post" action="{{ repo.url }}/wiki/{% if exists %}{{ slug }}{% else %}_new{% endif %}/edit">

  <input type="hidden" name="_csrf" value="{{ shell.csrf }}">

  <label for="wtitle">Title</label><input type="text" id="wtitle" name="title" value="{{ title }}" required maxlength="100" placeholder="Getting Started">

  <p class="small mute">The page's address is its title with dashes for spaces: <code>{{ repo.url }}/wiki/Getting-Started</code>. Link to another page as <code>[Other page](Other-page)</code>.</p>

  <label for="wcontent">Content (Markdown)</label><textarea id="wcontent" name="content" class="md code" rows="22" required>{{ content }}</textarea>

  <label for="wmessage">Change message (optional)</label><input type="text" id="wmessage" name="message" maxlength="200" placeholder="{% if exists %}Update {{ title }}{% else %}Create the page{% endif %}">

  <p class="small mute">Saved as a change in the wiki's repository, authored by you and signed by this hub as your delegate.</p>

  <button type="submit">{% if exists %}SAVE{% else %}CREATE PAGE{% endif %}</button> <a class="go" href="{{ repo.url }}/wiki{% if exists %}/{{ slug }}{% endif %}">Cancel</a>

</form>

{% endblock %}

{% extends "base.html" %}

{% import "repo_tabs.html" as m %}

{% block title %}History of {{ title }} · wiki · {{ repo.owner }}/{{ repo.name }}{% endblock %}

{% block tabs %}{% call m::tabs(repo, "wiki") %}{% endblock %}

{% block content %}

<div class="head"><h1>History of {{ title }}</h1><p class="small"><a class="go" href="{{ repo.url }}/wiki/{{ slug }}">Back to the page</a></p></div>

{% if entries.is_empty() %}<p class="empty">No changes.</p>{% else %}

<div class="table"><table>

<tr><th>Change</th><th>Message</th><th>By</th><th>When</th></tr>

{% for c in entries %}<tr><td><code>{{ c.short }}</code></td><td>{{ c.title }}</td><td>{% if let Some(a) = c.author.account %}<a href="/{{ a }}">{{ c.author.name }}</a>{% else %}{{ c.author.name }}{% endif %}{% if let Some(v) = c.via %} <span class="mute">via {{ v.name }}</span>{% endif %}</td><td><time title="{{ c.when_ms|when_i }}">{{ c.when_ms|ago_i }}</time></td></tr>{% endfor %}

</table></div>

{% endif %}

{% endblock %}

{% extends "base.html" %}

{% import "repo_tabs.html" as m %}

{% block title %}Pages · wiki · {{ repo.owner }}/{{ repo.name }}{% endblock %}

{% block tabs %}{% call m::tabs(repo, "wiki") %}{% endblock %}

{% block content %}

<div class="head"><h1>Wiki pages <small>{{ pages.len() }}</small></h1>

  <p class="small">{% if can_edit %}<a class="go" href="{{ repo.url }}/wiki/_new">New page</a> {% endif %}<a class="go" href="{{ repo.url }}/wiki">Home</a></p>

</div>

<form class="search-row" method="get" action="{{ repo.url }}/wiki/_pages"><input type="search" name="q" value="{{ q }}" placeholder="Search the wiki" aria-label="Search the wiki"><button type="submit">SEARCH</button></form>

{% if !q.is_empty() %}

<section class="panel"><h2>{{ hits.len() }} {% if hits.len() == 1 %}page mentions{% else %}pages mention{% endif %} “{{ q }}”</h2>

  {% if hits.is_empty() %}<p class="mute small">Nothing.</p>{% else %}<ul class="plain">{% for (slug, line) in hits %}<li><a href="{{ repo.url }}/wiki/{{ slug }}">{{ crate::wiki::title_of(slug) }}</a>{% if !line.is_empty() %} <span class="small mute">{{ line }}</span>{% endif %}</li>{% endfor %}</ul>{% endif %}

</section>

{% endif %}

{% if pages.is_empty() %}<p class="empty">No pages yet.</p>{% else %}

<ul class="plain">{% for p in pages %}<li><a href="{{ repo.url }}/wiki/{{ p }}">{{ crate::wiki::title_of(p) }}</a></li>{% endfor %}</ul>

{% endif %}

{% endblock %}

- **Wikis (#104).** Each repository can have a wiki: Markdown pages kept as an Oxygen repository of their own, read and edited on the web (with history, a sidebar, a page list and search) or cloned and pushed as `OWNER/NAME.wiki`. Web edits are signed changes, as code edits are. Settings › Advanced deletes the wiki data.

    if name.name.ends_with(crate::wiki::SUFFIX) {

        return Err(ApiError(StatusCode::BAD_REQUEST, "a name cannot end in .wiki: that is the address of a repository's wiki".into()));

    }

pub mod wiki;

    /// Wikis, one Oxygen repository per repository (hub spec §6.11).

    pub wikis: Arc<Repos>,

    let wikis = Arc::new(Repos::new(config.data.join("wikis")));

    let backend = protocol::HubBackend::new(

        repos.clone(),

        wikis.clone(),

        db.clone(),

        config.auth.push_tokens.clone(),

        tokio::runtime::Handle::current(),

    );

        wikis,

    /// Wikis, reached as `OWNER/NAME.wiki` (hub spec §6.11).

    wikis: Arc<Repos>,

    pub fn new(

        repos: Arc<Repos>,

        wikis: Arc<Repos>,

        pool: db::Pool,

        site_tokens: Vec<String>,

        runtime: tokio::runtime::Handle,

    ) -> HubBackend {

        HubBackend { repos, wikis, pool, site_tokens, runtime, app_hint: Arc::new(std::sync::Mutex::new(None)) }

        // `NAME.wiki` is the repository's wiki (§6.11); the row knows the

        // current name, so a transferred repository still answers to its

        // old one (#108).

        let (parent, is_wiki) = crate::wiki::parent_of(&parsed);

        let row = self.row(&parent)?;

        let store = if is_wiki { &self.wikis } else { &self.repos };

        store.open(&name).map_err(|e| match e {

        let (parent, _) = crate::wiki::parent_of(&parsed);

        let row = self.row(&parent)?;

                let covered = token.covers(&parsed.to_string()) || token.covers(&current) || token.covers(&parent.to_string());

                (role, needed && covered)

        if crate::wiki::parent_of(&parsed).1 {

            return Some(crate::wiki::BOOKMARK.into());

        }

        // A wiki push starts no run and rings no webhook.

        if crate::wiki::parent_of(&parsed).1 {

            return;

        }

mod wiki;

        .route("/{owner}/{name}/settings/wiki/delete", post(repo_settings::wiki_delete))

        .route("/{owner}/{name}/wiki", get(wiki::home))

        .route("/{owner}/{name}/wiki/_pages", get(wiki::pages))

        .route("/{owner}/{name}/wiki/_new", get(wiki::new_form))

        .route("/{owner}/{name}/wiki/_raw/{*path}", get(wiki::raw))

        .route("/{owner}/{name}/wiki/{slug}", get(wiki::show))

        .route("/{owner}/{name}/wiki/{slug}/edit", get(wiki::edit_form).post(wiki::save))

        .route("/{owner}/{name}/wiki/{slug}/history", get(wiki::history))

        .route("/{owner}/{name}/wiki/{slug}/delete", post(wiki::delete))

    /// Whether the repository has a wiki (§6.11).

    pub wiki: bool,

            wiki: crate::repos::RepoName::new(&row.owner, &row.name).is_some_and(|n| app.wikis.exists(&n)),

    if name.name.ends_with(crate::wiki::SUFFIX) {

        return Ok(fail("A name cannot end in .wiki: that is the address of a repository's wiki."));

    }

        if app.wikis.exists(&repo) {

            app.wikis.rename(&repo, &dest).ok();

        }

}

/// `POST /{owner}/{name}/settings/wiki/delete`: the wiki to the trash (#104).

pub async fn wiki_delete(

    State(app): State<Shared>,

    viewer: Viewer,

    Path((owner, name)): Path<(String, String)>,

    Form(f): Form<DeleteForm>,

) -> Result<Page<RepoSettingsPage>, Error> {

    let shell = Shell::new(&app, &format!("/{owner}/{name}/settings"), &viewer);

    let (repo, row, role) = lookup_role(&app, &shell, &viewer, &owner, &name, Access::Admin).await?;

    csrf(&viewer, &f.csrf_token, &shell)?;

    if f.confirm.trim() != repo.to_string() {

        return settings_page(&app, shell, row, role, None, Some("Type the repository's full name to confirm.".into())).await;

    }

    if !crate::wiki::exists(&app, &repo) {

        return settings_page(&app, shell, row, role, None, Some("This repository has no wiki.".into())).await;

    }

    let _guard = app.wikis.write_guard(&repo).await;

    crate::wiki::trash(&app, &repo).map_err(|e| Error::from_repo(shell.clone(), e))?;

    drop(_guard);

    accounts::audit(&app.db, viewer.account(), "wiki.data_deleted", &repo.to_string(), "moved to trash").await.ok();

    settings_page(&app, shell, row, role, Some("The wiki is in the trash; a new first page starts a fresh one.".into()), None).await

    crate::wiki::trash(&app, &repo).ok();

#[tokio::test(flavor = "multi_thread")]

async fn a_wiki_is_edited_on_the_web_and_cloned_and_pushed_as_name_dot_wiki() {

    hermetic();

    let dir = tempfile::tempdir().unwrap();

    let mut config = Config::load(dir.path()).unwrap();

    config.auth.push_tokens = vec!["site".into()];

    config.registration.mode = "open".into();

    let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();

    let port = listener.local_addr().unwrap().port();

    config.server.base_url = format!("http://127.0.0.1:{port}");

    let app = oxygenhub::build(config).await.unwrap();

    let router = oxygenhub::router(app.clone());

    tokio::spawn(async move { axum::serve(listener, router).await.unwrap() });

    let base = format!("http://127.0.0.1:{port}");

    let app = &app;

    let r = send(app, "POST", "/register", None, Some("username=andy&email=a%40example.com&password=correct-horse-battery")).await;

    let andy = r.cookie.unwrap();

    let andy_id = db::accounts::account_by_name(&app.db, "andy").await.unwrap().unwrap().id;

    let repo = RepoName::parse("andy/demo").unwrap();

    app.repos.create(&repo, None).unwrap();

    db::repos::create(&app.db, "andy", "demo", "", hub_api::Visibility::Public).await.unwrap();

    // Andy delegates to the hub key and links the identity, as for code edits.

    let work = tempfile::tempdir().unwrap();

    let mut client = Repo::init(work.path()).unwrap();

    client.create_identity("Andy McCall", "[email protected]", IdentityScope::Repo).unwrap();

    client.config.set("core.sign", "change").unwrap();

    client.config.set("remote.origin.url", &format!("{base}/andy/demo")).unwrap();

    client.config.set("remote.origin.token", "site").unwrap();

    client.save_config().unwrap();

    write(work.path(), "a.txt", b"one\n");

    client.snapshot("t").unwrap();

    client.commit("first", &[]).unwrap();

    assert!(client.push("origin", false).unwrap().iter().all(|r| r.ok));

    client.delegate_add(app.hub_key.identity.clone(), oxy_core::identity::Scope::CHANGES | oxy_core::identity::Scope::REFS, None).unwrap();

    let key = client.config.author_key.unwrap();

    let id = client.identity(&key).unwrap();

    db::accounts::link_identity(&app.db, andy_id, &key.to_hex(), &id.name, &id.email, &id.encode()).await.unwrap();

    // No wiki yet: the tab shows for a writer, the page explains.

    let page = send(app, "GET", "/andy/demo/wiki", Some(&andy), None).await;

    assert_eq!(page.status, StatusCode::OK, "{}", page.body);

    assert!(page.body.contains("No wiki yet") && page.body.contains(">Wiki</a>") && page.body.contains("andy/demo.wiki"), "{}", page.body);

    assert!(!send(app, "GET", "/andy/demo", None, None).await.body.contains(">Wiki</a>"), "no tab for a reader without a wiki");

    // A repository cannot take the wiki's address.

    let csrf_n = csrf_of(&send(app, "GET", "/new", Some(&andy), None).await.body);

    let r = send(app, "POST", "/new", Some(&andy), Some(&format!("_csrf={csrf_n}&owner=andy&name=demo.wiki&visibility=public"))).await;

    assert!(r.body.contains("cannot end in .wiki"), "{}", r.body);

    // The first page, with a link to a page not yet written.

    let csrf = csrf_of(&page.body);

    let r = send(

        app,

        "POST",

        "/andy/demo/wiki/_new/edit",

        Some(&andy),

        Some(&format!("_csrf={csrf}&title=Home&content={}", enc("# Welcome\n\nSee [the guide](Guide).\n"))),

    )

    .await;

    assert_eq!(r.status, StatusCode::SEE_OTHER, "{}", r.body);

    assert_eq!(r.location.as_deref(), Some("/andy/demo/wiki/Home"));

    let home = send(app, "GET", "/andy/demo/wiki", None, None).await.body;

    assert!(

        home.contains("Welcome") && home.contains("href=\"/andy/demo/wiki/Guide\"") && home.contains("Last changed by Andy McCall"),

        "{home}"

    );

    assert!(send(app, "GET", "/andy/demo", None, None).await.body.contains(">Wiki</a>"), "the tab shows to everyone now");

    let missing = send(app, "GET", "/andy/demo/wiki/Guide", Some(&andy), None).await.body;

    assert!(missing.contains("no page called <strong>Guide</strong>") && missing.contains("_new?title=Guide"), "{missing}");

    // An edit, then a rename: history follows, the old address is empty.

    let r = send(

        app,

        "POST",

        "/andy/demo/wiki/Home/edit",

        Some(&andy),

        Some(&format!("_csrf={csrf}&title=Home&content={}&message=Say+more", enc("# Welcome\n\nMore.\n"))),

    )

    .await;

    assert_eq!(r.location.as_deref(), Some("/andy/demo/wiki/Home"), "{}", r.body);

    let hist = send(app, "GET", "/andy/demo/wiki/Home/history", None, None).await.body;

    assert!(hist.contains("Say more") && hist.contains("Create Home"), "{hist}");

    let r = send(

        app,

        "POST",

        "/andy/demo/wiki/Home/edit",

        Some(&andy),

        Some(&format!("_csrf={csrf}&title=Start+Here&content={}", enc("# Start\n"))),

    )

    .await;

    assert_eq!(r.location.as_deref(), Some("/andy/demo/wiki/Start-Here"), "{}", r.body);

    assert!(send(app, "GET", "/andy/demo/wiki/Start-Here", None, None).await.body.contains("<h1>Start Here</h1>"));

    assert!(send(app, "GET", "/andy/demo/wiki", None, None).await.body.contains("no page called <strong>Home</strong>"));

    let pages = send(app, "GET", "/andy/demo/wiki/_pages?q=start", None, None).await.body;

    assert!(pages.contains("href=\"/andy/demo/wiki/Start-Here\"") && pages.contains("mentions"), "{pages}");

    // By client: clone the wiki, add a page, push it.

    let wdir = tempfile::tempdir().unwrap();

    let mut w = Repo::clone(&format!("{base}/andy/demo.wiki"), wdir.path()).unwrap();

    assert_eq!(std::fs::read_to_string(wdir.path().join("Start-Here.md")).unwrap(), "# Start\n");

    w.create_identity("Andy McCall", "[email protected]", IdentityScope::Repo).unwrap();

    w.config.set("core.sign", "change").unwrap();

    w.config.set("remote.origin.token", "site").unwrap();

    w.save_config().unwrap();

    write(wdir.path(), "Guide.md", b"# Guide\n\nPushed from a clone.\n");

    w.snapshot("t").unwrap();

    w.commit("Add the guide", &[]).unwrap();

    assert!(w.push("origin", false).unwrap().iter().all(|r| r.ok), "pushed to the wiki");

    let guide = send(app, "GET", "/andy/demo/wiki/Guide", None, None).await.body;

    assert!(guide.contains("Pushed from a clone"), "{guide}");

    assert!(

        db::flow::runs(&app.db, db::repos::get(&app.db, "andy", "demo").await.unwrap().unwrap().id, 10, None)

            .await

            .map(|r| r.is_empty())

            .unwrap_or(true),

        "a wiki push starts no run"

    );

    // Delete a page, then the whole wiki from Advanced settings.

    let r = send(app, "POST", "/andy/demo/wiki/Guide/delete", Some(&andy), Some(&format!("_csrf={csrf}"))).await;

    assert_eq!(r.status, StatusCode::SEE_OTHER, "{}", r.body);

    assert!(send(app, "GET", "/andy/demo/wiki/Guide", None, None).await.body.contains("no page called"));

    let settings = send(app, "GET", "/andy/demo/settings", Some(&andy), None).await.body;

    assert!(settings.contains("DELETE WIKI DATA"), "{settings}");

    let r = send(

        app,

        "POST",

        "/andy/demo/settings/wiki/delete",

        Some(&andy),

        Some(&format!("_csrf={}&confirm=andy%2Fdemo", csrf_of(&settings))),

    )

    .await;

    assert!(r.body.contains("The wiki is in the trash"), "{}", r.body);

    assert!(send(app, "GET", "/andy/demo/wiki", Some(&andy), None).await.body.contains("No wiki yet"));

}

Non-goals for 1.0: hosting Git repositories natively (§14 covers mirrors), a marketplace, discussions, GitHub Pages, and federation between hubs. The runner is specified separately (§13, `docs/runner.md`) and is not required for 1.0.

### 6.11 Wiki (done 2026-10-04)

A repository may have a **wiki** (oxygenhub#104): Markdown pages kept as an Oxygen repository of their own under `<data>/wikis/<owner>/<name>`, with no row of its own; it follows the repository's visibility, roles, archiving, transfer and deletion. A page `Getting-Started` is the file `Getting-Started.md` at the root of bookmark `main`; `_Sidebar.md` is shown beside every page, and `Home` is the front page. On the web (`/{owner}/{name}/wiki`, `/wiki/{page}`, `/wiki/{page}/edit`, `/wiki/{page}/history`, `/wiki/_pages` with a search over titles and text, `/wiki/_raw/{path}` for images): readers read, writers create, edit, rename and delete pages, and every edit is a change authored by the user and signed by the hub as their delegate, exactly as a code edit (§6.9), so it needs the same delegation. Links between pages are relative (`[Other](Other)`). By client, the wiki is `oxy clone HUB/{owner}/{name}.wiki`: the wire protocol maps that name onto the wiki store with the repository's permissions, pushes need write access and not archived, start no run and ring no webhook; a repository can therefore not be named `*.wiki`. The Wiki tab shows when a wiki exists or the viewer may start one. Settings › Advanced › Delete wiki data moves the wiki to the trash. Audited as `wiki.edited`, `wiki.deleted`, `wiki.data_deleted`; webhooks get a `wiki` event.

<section class="panel" id="wiki">

  <h2>Wiki</h2>

  <p>A repository's wiki is Markdown pages kept as an Oxygen repository of their own: edit them under the <strong>Wiki</strong> tab (every edit is a signed change, so it needs the same delegation as editing code), or clone and push them as <code>oxy clone {{ shell.base_url }}/OWNER/NAME.wiki</code>. Pages are <code>Name.md</code> on <code>main</code>; <code>_Sidebar.md</code> is the sidebar; link between pages with <code>[Other](Other)</code>.</p>

</section>

    <div><strong>Delete wiki data</strong><p class="small mute">{% if repo.wiki %}The wiki's repository moves to the trash with its history; a new first page starts a fresh one.{% else %}This repository has no wiki.{% endif %}</p></div>

    {% if repo.wiki %}<details class="danger-act"><summary class="danger-btn">Delete wiki data</summary>

      <form class="card" method="post" action="{{ repo.url }}/settings/wiki/delete">

        <input type="hidden" name="_csrf" value="{{ shell.csrf }}">

        <label for="wconfirm">Type <code>{{ repo.owner }}/{{ repo.name }}</code> to confirm</label><input type="text" id="wconfirm" name="confirm" required autocomplete="off">

        <button type="submit">DELETE WIKI DATA</button>

      </form>

    </details>{% else %}<button class="danger-btn" type="button" disabled>Delete wiki data</button>{% endif %}

    {% if repo.wiki || repo.can(crate::auth::Access::Write) %}<a href="{{ repo.url }}/wiki"{% if tab == "wiki" %} class="on" aria-current="page"{% endif %}>Wiki</a>{% endif %}