Serve static Markdown-based websites from a user's Nextcloud files, with in-browser editing for owners and collaborators.
Author: Frederik Orellana, Technical University of Denmark (fror@dtu.dk)
License: AGPL-3.0
files_picocms exposes any directory in a user's NC files as a
Pico CMS website at a stable public URL. Pages are
Markdown files; metadata (title, date, author, access, …) lives in YAML
front-matter. The app bundles a copy of Pico 2.x, Parsedown Extra, and a
blog-style Twig theme; no composer install or build step is required.
/remote.php/sites/{name}[/{page}] — named site (registered in DB)
/remote.php/users/{email}[/{page}] — user public page
These are the default link form — the sites and users remote services —
which work on any web server with no rewrite. All requests are handled by
appinfo/serve.php, which runs inside the Nextcloud bootstrap environment and
has full access to NC services.
By default the app generates /remote.php/sites/… links, which need no web-server
configuration. Pretty URLs (/sites/{name}, /users/{email}) are opt-in and
require two pieces — the app never assumes the rewrite is present:
- Web server rewrite (Apache). Recommended: to the app's own entry script, so that site links also work for logged-in readers arriving from an e-mail or another website (see Links from other sites while logged in below):
RewriteRule ^sites/ /apps/files_picocms/appinfo/sites.php [QSA,L]
RewriteRule ^users/ /apps/files_picocms/appinfo/sites.php [QSA,L]The minimal form, straight to remote.php, also works, but answers such
readers with 412:
RewriteRule ^/?sites/(.*)$ /remote.php/sites/$1 [PT,L]
RewriteRule ^/?users/(.*)$ /remote.php/users/$1 [PT,L]or Caddy (remote.php form):
@picocms path /sites /sites/* /users /users/*
rewrite @picocms /remote.php{uri}The target is /remote.php/sites/…, NOT …/files_picocms/sites/…:
Nextcloud derives the remote service name from the original
REQUEST_URI (which internal rewrites do not change), so the first path
segment of the public URL must itself be a registered service. The app
registers sites and users as remote services in info.xml for
exactly this purpose (on manual installs make sure
occ config:app:get core remote_sites returns
files_picocms/appinfo/serve.php, likewise remote_users — the app
installer writes these on install/update).
- Tell the app to generate matching links, in
config.php:
'files_picocms.url_prefix' => '',The parameter is the URL path prefix for all generated site/user links
(default /remote.php — the no-rewrite form). Incoming requests are accepted
in both forms regardless of the setting, and redirects between nodes preserve
whichever form the visitor used — but only set '' together with the rewrite
rules, and set it the same on every node: with '' and no rules, every generated
link 404s (the page loads via remote.php but its CSS/JS, linked with the pretty
prefix, do not — so the site renders unstyled). Note that /sites and
/users then become reserved top-level paths on the host.
Core's base.php refuses every script except index.php, public.php and
cron.php with 412 {"error":"Strict Cookie has not been found in request"}
when the browser sends cookies but not Nextcloud's SameSite=Strict marker,
which is exactly what a browser does when a reader who has been on the server
before follows a link from an e-mail or another website. Served through
remote.php, a site link mailed to a logged-in collaborator therefore fails.
appinfo/sites.php is the app's own entry script for site pages: it answers
such a page view (GET/HEAD) before booting Nextcloud with a tiny page that
reloads the same address (appinfo/samesite.php; the reload starts on this
site, so all cookies come along; a 30 s guard cookie prevents a second reload),
then boots and hands over to serve.php as remote.php does. To use it, point
the rewrites at it instead of remote.php (internal rewrites; the address the
visitor sees is unchanged), including direct /remote.php/sites/… links:
RewriteRule ^sites/ /apps/files_picocms/appinfo/sites.php [QSA,L]
RewriteRule ^users/ /apps/files_picocms/appinfo/sites.php [QSA,L]
RewriteRule ^remote\.php/(?:sites|users)/ /apps/files_picocms/appinfo/sites.php [QSA,L]It serves the original address; for an address that is not itself a site
address, put the site address after the script:
RewriteRule ^terms/?$ /apps/files_picocms/appinfo/sites.php/remote.php/sites/terms [QSA,L].
Catalogue records (landing.php) do the same reload.
Setup check. When url_prefix is empty, the app registers a Nextcloud
setup check (PrettyUrlsCheck) that probes /sites/__picocms_probe over HTTP
and, if the rewrite isn't reaching the app, raises a warning in
Admin → Administration settings → Overview with the fix. It's web-server
agnostic (it tests actual behaviour, not config) — so a fresh install that
forgot the rewrite is flagged rather than silently serving unstyled pages.
A link share whose owner ticked "List in the public datasets catalog"
(share attribute files_picocms:catalog_listed) is a catalogue record.
Its address is its public link, /shared/<token>, which then shows the
record's landing page (description, files, citation, download) instead of
the file browser; "Browse files" leads on to Nextcloud's share page
/index.php/s/<token>. A record with a DOI (files_publish "Assign DOI…")
is also shown at /doi/<suffix>, and once it leaves the catalogue that
address shows a withdrawn page built from DataCite's public record (410).
The web server sends both forms to appinfo/landing.php (internal rewrite;
mfsbsd nc_htaccess_custom.conf), which renders the catalogue site
(first of files_picocms.repository_sites) in landing mode, or sends an
unlisted /shared/ link on to /index.php/s/<token> with its query. Like
sites.php, it first reloads a page view that arrives from another site without
Nextcloud's strict cookie (see Links from other sites while logged in), so a
record link in an e-mail also works for a reader who is logged in.
?download and ?path= forms are redirected straight to the data by the
web server. The catalogue is cached for 5 minutes (APCu); a record not found in
the cache is looked up again uncached.
Nextcloud's share page records every viewer open and close and every address
tweak (?openfile, &editing=false, ?dir=/) as a new browser-history entry:
leaving a single shared notebook from a blog post took five clicks on Back. The
app's script turns those into replacements within one folder: a file the
visitor opens gets one entry (Back closes it), closing it with its close button
steps back over that entry, and the automatic preview of a single-file share adds
none. Changing folder keeps its own entry, so Back still goes up a folder.
Application::boot registers the script as an init script for /s/…
addresses, because the first entry is pushed while Nextcloud's own init scripts
run. If a Nextcloud upgrade renames those parameters, the rules stop matching and
the page behaves as stock.
- Unlisted. A record whose item carries the tag
unlisted(files_picocms.unlisted_tag) keeps its page at its own address but is left out of every list: the catalogue, the front page, featured. The page says so ("Not listed in the catalogue …") and tells search engines not to index it (noindex). Use it to let an owner see their real record before agreeing to list it; removing the tag lists it. - Restricted files. When the record's link has a password, or files_sharding's "Require login", the page shows a Files line ("Password-protected — ask the contact for access" / "For logged-in users … only"), offers no Download or Run this notebook, and its schema.org data says the files are not freely accessible. Browse files leads to Nextcloud's password or login prompt. The metadata, citation and the list of file names stay public.
- Embargo = both: an unlisted record with a password on its link: the metadata can be cited and passed on, the files are not open yet. Lifting it is removing the tag and the password.
Citations: a creator in {braces} or that looks like an organisation
(parentheses, digits, words like University, Collaboration, Team, Systems) is
kept whole instead of being split into given and family names; within one
creator entry (creators are separated by ;), "A and B" are two people.
A published dataset is frozen - read-only for everyone, its owner included:
- an item whose public link is listed in the catalogue (share attribute
files_picocms:catalog_listed). Unticking "List in the public datasets catalog" unfreezes it; the owner can edit and list it again. - an item with a DOI in its DataCite record (meta_data schema on the system tag
DataCite, keydoi, written by files_publish's "Assign DOI"). This holds even if the link is unlisted or deleted, andPOST /api/v1/catalogrefuses to unlist it (403): a DOI promises that the data behind it does not change. Changes are published as a new version - a new catalogue entry, with or without its own DOI - and the old entry's metadata links to it.
Enforcement is a storage wrapper on users' home storages (core's DirPermissionsMask, over the set of frozen paths, looked up once per request in Service/FrozenDatasets.php). Every write path ends at the owner's storage - web, WebDAV, sync clients, batch jobs, collaborators on other nodes - so all are covered; permissions show as read-only in Files and the clients. A folder containing a frozen item cannot be deleted or moved to another folder (WebDAV requires delete permission on the source of a move), but it can be renamed in place: the data does not change, the public link keeps working and the item stays frozen. Registered at priority 0, outside the trash bin (1), so a delete is refused before it becomes a move to the trash. Metadata lives in the database and stays editable. Core refuses to share a frozen item with edit rights; an editable share made before listing loses its write access while listed.
All optional; unset, the app behaves like a plain app-store install.
| Key | Description |
|---|---|
files_picocms.url_prefix |
URL prefix for generated site links; '' together with the web-server rewrite gives pretty /sites/{name} URLs (default /remote.php, see Pretty URLs) |
files_picocms.brand_name |
Service name used in the welcome dialog, the help page and the wordmark backlink on the service's own sites (default Nextcloud) |
files_picocms.brand_blurb |
One-line service description shown in the welcome dialog |
files_picocms.frontpage_site |
Site served at the bare root / (default welcome) |
files_picocms.catalog_label |
Label of the public-data catalog listing |
files_picocms.featured_tag |
Name of the tag that marks a catalogue record as featured (default featured; create it admin-only with occ tag:add featured restricted). Featured records sort first and are shown in a marked box on the catalogue and the front page |
files_picocms.unlisted_tag |
Name of the tag that keeps a catalogue record out of all lists while its page stays reachable at its address (default unlisted; see Unlisted records). Empty string disables it |
files_picocms.repository_sites |
Site names whose top-left backlink points at the frontpage site rather than the site itself (the public-data catalog sites) |
files_picocms.footer_html |
Shared footer line (HTML) rendered by every theme with a footer |
files_picocms.favicon |
Shared favicon for sites that set none (absolute or root-relative; default: the frontpage theme's favicon.svg) |
files_picocms.help_docs_url |
Own documentation URL; makes the stock /settings/help page lead with it (see HelpPageScriptListener) |
files_picocms.hide_dev_notice |
true hides the stock "Reasons to use Nextcloud in your organization" block and social buttons at the bottom of Settings → Personal info (CSS only, no core change) |
Place a _config.md file at the site root (or in any subdirectory for
sub-site config). It is never rendered as a page (leading _ is blocked).
Recognised front-matter keys:
| Key | Default | Description |
|---|---|---|
access |
public |
public — anyone; private — owner and users the folder is shared with (NC share permissions honoured). The old service's shared is not supported and is treated as private — re-head migrated content. |
theme |
blog |
Theme directory name under themes/ |
title |
site name | Overrides the DB-registered site name |
description |
— | Passed to Pico; used by the theme |
author |
— | Author name, available to themes |
EditLinks |
— | yes to show per-post Edit buttons |
icon |
— | Nav-bar icon, path relative to site root (no longer doubles as favicon) |
favicon |
NC favicon | Path to favicon relative to site root. Unset, a page-level Favicon: applies, else config.php files_picocms.favicon, else the frontpage theme's favicon.svg — the welcome page's icon, so all sites share one tab icon. |
Backlink |
none on user sites | Text/HTML blob rendered as the service backlink in the theme's brand slot. The standard wordmark (files_picocms.brand_name → frontpage) is shown only on the service's own sites: the frontpage, the repository/catalog sites and sites owned by the content account (app config content_user). User-created sites carry no wordmark unless they set Backlink. The team theme has no brand slot at all. |
When a site is created through the wizard (POST /create), a commented
default _config.md is written to the site root, pre-populated with the
site name, chosen theme, and a detected or copied img/data_icon.png.
Keys in a page's own front matter arrive in the templates as meta.* — a
different namespace from _config.md (config.*), and some names exist in
both with different meanings. Icon is the notorious one: in _config.md it
is the nav-bar icon (and favicon fallback), in index.md it is the headline
image. Keys the bundled themes read:
| Key | Where | Themes | Description |
|---|---|---|---|
Title, Description, Author, Date |
any page | all | Standard Pico page data; Description doubles as the post subtitle (blog) |
Site |
index.md |
blog | Site title shown in the headline (overrides the registered name) |
Tagline |
index.md |
blog, default | Subtitle under the site title |
Icon |
index.md |
blog | Image shown next to the headline (header-icon) |
Img |
any page | blog | Banner background image of the page/post header |
IndexImage |
post | blog | Thumbnail shown under the post preview on the index |
Labels |
post | blog, team | Comma-separated labels → clickable chips + search/labels:<label> |
Access |
any page | all | public / private, see Who can write — a page-level override of the site default |
Template |
any page | all | Template name (post, search, profile, …) |
Theme |
index.md |
all | Theme for this site (same as _config.md theme) |
Toc |
any page | default, briefing | true → table of contents |
Social |
index.md |
blog, default | Map of url: icon rendered as footer icons |
Footer |
index.md |
default | Footer HTML for this site; unset → the shared footer from config.php files_picocms.footer_html (the frontpage's line) |
Robots |
any page | all | <meta name="robots"> content |
Terms, as the code uses them:
- Owner — the NC account whose home the site folder lives in: the
uidof the site's registry row, and the NC owner of every file in it. It is not theAuthor:header. Files a collaborator saves through the site's editor are still owned by this account (the write proxy writes as the site owner). - Scope — the registered site folder and everything below it. Access is
computed once per request for the site folder as a whole, never per page:
serve.phplooks up the current user's share on the site folder's node, and Pico's content directory is that folder, read recursively. Subfolders inherit; there is no per-file or per-subfolder permission. (Site:headers are display titles only and carry no permission meaning.) - Collaborator — a logged-in user holding an NC share of the site folder
with update permission (local user, group, or cross-silo federated share —
see Share detection below). A read-only share gives reading of a
privatesite and nothing more.
| Right | Owner | Collaborator (update share) | Everyone else |
|---|---|---|---|
read a public site |
✓ | ✓ | ✓ |
read a private site |
✓ | ✓ (any share, read or write) | – |
| create a new page anywhere in the site folder | ✓ | ✓ | – |
| edit any page, subfolders included | ✓ | – | – |
edit a page whose Author: header equals their own uid |
✓ | ✓ | – |
Themes receive this as two Twig variables and must gate their controls
consistently: writable (owner or collaborator) shows the create/"Write"/
"Show files" control; editable (owner only) — or writable together with
oc_user == meta.author — shows "edit this page". The blog, team, default and
briefing themes follow this; the documentation theme is a plain viewer with no
edit UI.
Everyone without a share, including a logged-in user, is denied on a private
site (fail-closed), so read-only sharing works for confidential material.
serve.php runs two strategies to determine the current user's access. A share
grants read; a share carrying update permission also grants write. Both
are fail-closed — no matching share means no access:
Strategy 1 — local mount lookup (same silo)
If the collaborator is on the same NC instance as the owner, NC's
IRootFolder::getById() finds the shared node in the collaborator's mount
tree. If found, the folder is shared with them → read; if the node also
reports isUpdateable() → write. Handles standard local TYPE_USER shares.
Strategy 2 — outgoing shares from the owner (cross-silo + groups)
serve.php iterates the owner's outgoing TYPE_REMOTE, TYPE_USER and TYPE_GROUP
shares of the site folder and grants access if the current user is the
recipient: for user/federated shares by resolving the share_with cloud ID and
comparing UIDs (covers the sharded case where the owner is on silo2 and the
collaborator's federated account there matches the recipient); for TYPE_GROUP
shares by group membership. Read or write is granted per the share's
permissions. This is the sole read authority for private sites — the old
\OC\Files NC-API permission walk (unreliable in NC34, and it fail-opened)
has been removed.
All file writes (new posts, edits, comments) go through serve.php itself
rather than NC's WebDAV endpoint.
Why a proxy instead of WebDAV?
In a files_sharding trusted federation, federated shares between users on
different silos work correctly over WebDAV. For example, when alice (silo2)
shares her blog directory with bob@master, and bob's home silo is silo1,
the federation mount appears in bob's file tree on silo1. Bob can write to
alice's files on silo2 via silo1's WebDAV at
https://silo1.example.org/remote.php/webdav/{alice_mount}/. The
federation mechanism itself is sound.
However, the blog page is served from silo2, while bob's federation mount lives on silo1 — a different origin (different hostname or port). A direct WebDAV PUT from silo2 JS to silo1 WebDAV is a cross-origin request and requires:
- CORS headers on silo1's WebDAV endpoint
(Access-Control-Allow-Origin,Access-Control-Allow-Credentials: true) withCredentials: truein all Ajax calls so the browser sends bob's silo1 session cookie- The JS knowing bob's home silo URL (from
files_sharding)
This is achievable, but has two constraints worth noting:
Access-Control-Allow-Credentials: trueis required (so the browser sends the session cookie). The CORS spec forbids combining this with a wildcard origin (*), soAccess-Control-Allow-Originmust name the exact origin of each silo page — e.g.https://silo2.example.org. In a multi-silo setup this means a per-origin rule in each node's reverse-proxy config (Caddyheaderdirective or ApacheHeader setinside a<Location /remote.php/webdav/>).- All nodes must share the same parent domain (e.g.
example.org) so that domain-scoped NC cookies set on one node are sent by the browser to another.
The serve.php
proxy is self-contained: the JS writes to the same URL it was loaded from
(silo2, same origin, no CORS), serve.php checks write permission, then
writes through IRootFolder as the site owner. No per-deployment CORS
config needed.
Switching to native WebDAV (if CORS is already configured):
Revert davUrl() in blog.js to host + '/remote.php/webdav' + path,
restore $ocPath to the full WebDAV path (prepend $contentRelative),
set $pico->ocUserHomeUrl to the collaborator's home silo URL (via
FilesSharding\Lib::getServerForUser($currentUid)), and add
xhrFields: {withCredentials: true} to all Ajax calls. Remove the
PUT / GET?picocms_raw handlers from serve.php.
| Method | Path | Description |
|---|---|---|
PUT |
/remote.php/files_picocms/sites/{name}/{file}.{ext} |
Write or create a file (pages and theme uploads) |
DELETE |
same path | Delete a file |
GET?picocms_raw=1 |
…/{file}.md |
Return raw Markdown for the inline editor |
GET?picocms_list_images=1 |
site base | JSON list of images for the image picker |
Security constraints: extension whitelist (md plus media/document types:
png jpg jpeg gif svg webp pdf mp4 webm; raw read is .md only); path
traversal (..) rejected; write permission ($writeGranted) required.
Unhandled PUT/DELETE/POST requests get HTTP 405 — they never fall
through to page rendering. Asset serving is GET/HEAD-only so writes always
reach the proxies. $sitePath is rawurldecoded, so filenames with spaces
and non-ASCII characters work both for serving and through the proxies.
The blog theme bundles EasyMDE.
Clicking Edit on a post opens a full-page modal with a Markdown editor;
clicking Write on the index creates a new post file and opens the editor.
The editor uses davGet / davPut helpers in themes/blog/js/blog.js
(and themes/team/js/team.js for the team theme) which talk to the write
proxy above.
Sessions are per node. A visitor who is logged in on their home silo but opens a
site served by the master (all cloud-owned sites, for instance) has no
master session, so serve.php would see them as anonymous — no edit controls,
and no access to a private site — even when the folder is shared with them.
serve.php therefore hops through files_sharding's cluster SSO when it finds
no session but the cluster marker cookie (files_sharding_home, set by the
user's home node at login on the shared parent domain) names another node:
serve.php (master, no session, marker → silo8)
→ silo8/index.php/apps/files_sharding/sso/issue?target=<master>&return=<path>
→ master/index.php/apps/files_sharding/login?token=…&user=…&return=<path>
→ back to the page, now with a master session for the user's directory account
Share detection then finds the visitor's share of the site folder as usual
(the federated share to user@master is mounted for the directory account on
the master), so Write/Edit appear and private sites open.
A stale marker (no session at the home node either) comes straight back and the
page renders anonymously; a 60 s host-only cookie (files_sharding_sso_tried)
prevents the hop from repeating. The hop fires only on the master (see the
files_sharding README, Cluster SSO hop, for why the target is restricted).
Cross-node collaborators on silo-hosted sites still need a session on that
silo — a known limitation.
Set access: private in _config.md. Access is then limited to the owner and
whoever the site folder is shared with (user, group, or cross-silo federated;
read or write — see Share detection above). Everyone else is denied:
unauthenticated visitors get HTTP 403 (the site's content/403.md themed, or a
plain login-link page), and logged-in users without a share are refused too
(fail-closed). This makes private safe for confidential documentation shared
with specific people or a group.
The master holds the authoritative copy of the site registry
(oc_files_picocms) so that any node can resolve /sites/{name} and
redirect to the node hosting the site. Silos keep a local copy of their own
users' rows for serving.
- Mutations (
SiteService::addSite/removeSite, including renames) are written locally and forwarded to the master via files_sharding'sInterServerClient(internal/sites,internal/sites/delete). Forward failures are logged (master registry is now stale), not fatal. - Name uniqueness is global: before registering, a silo checks the name
against the master registry (
internal/lookup) and rejects names taken by users on other silos. - Serving (
serve.php): a local lookup miss on a silo triggers a master lookup; the response includes the owner's silo (server_url) and the visitor is redirected there with HTTP 307. On the master itself, a found site is redirected to the owner's silo viaShardingService::getUserServer()(owners without a silo assignment are homed on the master and served locally). - All of this is guarded with
class_exists/ config checks — without files_sharding the app works standalone on its local registry.
So https://cloud.example.org/remote.php/files_picocms/sites/myblog (the
master) always works regardless of which silo hosts the owner — the master
307s to e.g. https://silo1.example.org/....
The ocUserHomeUrl Twig variable is set to the current silo's base URL
(not master) so that internal links and asset URLs remain correct on silos.
The oc_cms_base Twig variable holds the full picocms site URL and is used
by the JS as the write proxy base. config.site_folder holds the site's
folder path relative to the owner's files root (used by the team theme's
Manage button to link into the NC Files app).
Themes live under themes/ (either in the site directory or in the app's
themes/ directory). Bundled themes: blog (Bootstrap 3, CSS derived from
Clean Blog, EasyMDE), team (sidebar navigation, EasyMDE inline editing),
documentation, default, and briefing. Theme CSS/JS files are named after
the theme (css/blog.css, js/team.js, …).
The briefing theme is a presentation-first layout for management reviews,
service reports, and one-page decision memos: a slate/petrol-teal institutional
palette, Georgia headings over a system-sans body, styled Markdown tables and
block-quote callouts, plus opt-in .stats / .price / .cards / .pill
utility blocks (via inline HTML) for richer one-pagers. It is deliberately the
leanest theme — only index.twig + style.css + a ~25-line vanilla-JS
"Show files" button, no jQuery, no bundled web fonts (Georgia and the system
stack are OS-native) — and prints cleanly to a single sheet. In-page editing is
out of scope; author the Markdown in Files, or use the team/blog theme when
inline editing is wanted. Front-matter keys it reads: eyebrow, tag, date,
footer (alongside the usual Title / description). Set Toc: true for the
upper-right table of contents (all themes support it); TocDepth: N caps the
deepest heading level listed (2–4, i.e. ##/###/####; 1 lists no headings,
just the page; default lists all). In briefing the box is fixed in the upper right
(folded by default) and has a Presentation mode checkbox, as in the blog theme:
ticked, clicking a TOC line shows only that section - its heading and everything up to
the next heading of the same or a higher level; the title block is hidden meanwhile. Theme asset links carry ?v=… (theme
files are cached for a day) - bump it when the theme's CSS/JS change.
Theme files (themes/…) are served directly without running Pico, so CSS/JS
assets load even before the page is rendered.
The team theme's sample content (sample-content/team/) is a complete
example research-group site aimed at group leaders: a public front page
with placeholder text in [brackets] and a self-explanatory "this is an
example site" banner, Research/People/Publications/Contact pages, a public
News section (posts with comments, auto-listed via Index: true in
news/index.md), and a private internal/ section (member-only pages —
demonstrates Access: private with a friendly "Members only" login prompt).
The wizard fills in Date/Author/Site automatically.
Note: a folder without an index.md gets a Pico-generated listing that
defaults to private; public sections must carry their own index.md with
Access: public. Also note Index: true parses as a YAML boolean — the
index.twig listing condition compares strictly (same as(true)) because a
loose true != "false" comparison is false in PHP/Twig.
New sites no longer copy the app's themes/ directory into the site folder
(data-copy-themes="no" in the wizard): sites track the app's themes, so
theme fixes reach all sites immediately, and site folders stay small. Users
who want to customise a theme can copy themes/{name} into their site folder
manually — site-local themes still take precedence.
All JS, CSS and fonts are bundled inside each theme; pages load nothing from external hosts:
- Google Fonts (Lora + Open Sans, latin/latin-ext woff2) are bundled as
css/fonts.css+fonts/google/per theme (fonts.cssat the theme root for thedefaulttheme). - Font Awesome is bundled (
css/font-awesome.css+fonts/fa-*); EasyMDE is initialised withautoDownloadFontAwesome: falseso it never injects its CDN stylesheet. - jQuery, Bootstrap and EasyMDE are theme-local files.
- MathJax 3.2.2 (
tex-mml-chtml+ woff-v2 fonts, plus the mhchem chemistry extension atinput/tex/extensions/mhchem.js, loaded by every theme's MathJax config vialoader.load: ['[tex]/mhchem']) is bundled once at the app level in3rdparty/mathjax/and served at{site}/mathjax/…by a dedicated serve.php branch — deliberately NOT underthemes/so the site wizard's copy-themes option does not duplicate ~1.5 MB into every site folder. The blog, team and default templates load it with$…$and\(…\)inline-math delimiters; the documentation theme uses the same shared copy (its own font-lessjs/tex-chtml.jswas dropped 2026-09-15).
The serve.php CSP is correspondingly strict — 'self' only for styles,
scripts, fonts and images (plus unsafe-inline/unsafe-eval for the themes'
inline JS). Keep it that way: when adding theme features, copy the asset into
the theme instead of referencing a CDN, or the CSP will block it.
All third-party code is bundled directly; no composer install is required.
| Library | Version | Location |
|---|---|---|
| Pico CMS | 2.x | 3rdparty/Pico/ |
| Parsedown | 1.x | 3rdparty/Parsedown.php |
| Parsedown Extra | 0.7 | 3rdparty/ParsedownExtra.php |
| Twig | 1.x | 3rdparty/Twig/ |
| Symfony/Yaml | — | 3rdparty/Yaml/ |
The app exposes three families of endpoints: the user-facing OCS API, the
shared-secret internal inter-server API, and the write-proxy endpoints
handled directly by serve.php (documented under Write proxy above).
Base URL:
/ocs/v2.php/apps/files_picocms/api/v1
Authentication: a logged-in Nextcloud session (with CSRF requesttoken) or
Basic auth with an app password. All requests need the header
OCS-APIREQUEST: true. Append ?format=json for JSON instead of XML.
Responses below describe the ocs.data payload. All endpoints operate on the
current user's sites; folder parameters are paths relative to the
user's home, e.g. /blog.
Implementation: routes in appinfo/routes.php, logic in
lib/Controller/ApiController.php → lib/Service/SiteService.php.
No parameters. Returns an array of rows:
[ { "uid": "alice", "site": "myblog", "path": "/blog", "gid": "" } ]site is the URL slug (/remote.php/files_picocms/sites/{site}), path the
folder in the user's files, gid an optional group owning the site.
| Param | Required | Description |
|---|---|---|
folder |
yes | Folder path to serve |
name |
yes | URL slug |
group |
no | Group ID for group-owned sites (default '') |
rename |
no | yes = rename the existing registration for folder to name instead of creating a new one (default no) |
Returns {"msg": "Added"}, or HTTP 400 {"error": "Name taken: …"} if the
slug is already registered (or, with rename=yes, if no registration exists
for folder).
| Param | Required | Description |
|---|---|---|
folder |
yes | Folder path of the registered site |
Returns {"msg": "Removed"} or HTTP 404 {"error": "Not found"}. The folder
and its files are not touched — the site just stops being served.
| Param | Required | Description |
|---|---|---|
folder |
yes | Destination folder (created if missing) |
name |
no | URL slug; defaults to the folder's basename |
content |
no | Sample-content source, path relative to the app dir (e.g. /sample-content/blog) or a file for single-page sites |
destination |
no | Subfolder of folder to copy content into; empty = site root |
theme |
no | Theme to set in the generated _config.md |
copyThemes |
no | yes = copy the app's themes/ into the site folder (default no) |
Copies the sample content (or the admin-configured sample folder, see
/sample-folder), registers the site, and writes a commented default
_config.md including a nav icon/favicon. Returns {"site": "{name}"},
HTTP 400 {"error": "Site name taken: …"}, or HTTP 500
{"error": "Failed to copy content"}.
Backs the Manage button in personal settings.
| Param | Required | Description |
|---|---|---|
folder |
yes | Folder path of the site |
content |
POST only | Full new _config.md content |
The config file is looked up first at {folder}/content/_config.md, then at
{folder}/_config.md; if neither exists, GET returns empty content and the
path where POST will create it (content/_config.md if a content/
subfolder exists, else the site root).
- GET returns
{"content": "---\ntitle: …", "file": "/blog/_config.md"} - POST returns
{"msg": "Saved"}or HTTP 500{"error": "Save failed"}
Controls whether /remote.php/files_picocms/users/{email} is served for the
current user.
- GET: no parameters, returns
{"serve": "yes"|"no"} - POST: parameter
serve=yesorno, echoes{"serve": "…"}
No parameters. Returns the default folder suggestions used by the personal-settings wizard:
{ "team_folder": "/team", "blog_folder": "/blog", "doc_folder": "/documentation",
"public_folder": "/public", "default_folder": "/website" }Configure a Nextcloud folder whose contents override the bundled
sample-content/ as the wizard source. Requires an admin session.
- GET: no parameters, returns
{"owner": "…", "path": "…"} - POST: parameters
owner(NC uid) andpath, returns{"msg": "Saved"}
Used by files_sharding silos to perform site operations against the master
(silos do not write the oc_files_picocms table locally). Called via
InterServerClient::postDirect/getDirect.
Base URL (plain JSON, not OCS):
/index.php/apps/files_picocms/internal
Authentication: Authorization: Bearer {files_sharding_shared_secret} — the
shared secret from config.php. All endpoints return HTTP 401
{"error": "Unauthorized"} on a missing/wrong token, and 401 always if the
secret is not configured. Implementation:
lib/Controller/InternalController.php.
These mirror the OCS endpoints but take an explicit uid (the acting user)
instead of using the session:
| Method | Path | Params | Returns |
|---|---|---|---|
| GET | /internal/sites |
uid |
array of site rows (as OCS GET /sites) |
| POST | /internal/sites |
uid, folder, name, group='', rename='no' |
{"msg": "Added"} / 400 |
| DELETE | /internal/sites |
uid, folder |
{"msg": "Removed"} / 404 |
| POST | /internal/sites/delete |
uid, folder |
alias for DELETE (InterServerClient cannot send DELETE) |
| GET | /internal/lookup |
site (slug) |
{"uid", "site", "path", "gid", "server_id", "server_url"} or {} if unknown — server_url is the owner's silo (empty = master-homed) |
| GET | /internal/serve-public |
uid |
{"serve": "yes"|"no"} |
| POST | /internal/serve-public |
uid, serve |
{"serve": "…"} |
| GET | /internal/sample-folder |
— | {"owner", "path"} |
| POST | /internal/sample-folder |
owner, path |
{"msg": "Saved"} |
| GET | /internal/userid |
email |
{"uid": "…"|null} — resolves an email to a NC uid |
/internal/lookup is what serve.php on a silo uses to resolve a site slug
to its owner before redirecting to the owner's silo.
No build step, no composer install. Copy the app directory into apps/ on
every node and reload PHP so OPcache picks up the changes:
for HOST in cloud.example.org silo1.example.org silo2.example.org; do
rsync -a files_picocms/ "$HOST:/var/www/nextcloud/apps/files_picocms/"
ssh "$HOST" 'service php8.3-fpm reload'
doneIn a single-node (non-sharded) installation just the one copy is needed.
- The write proxy (CORS workaround) can be replaced by native WebDAV if the
reverse proxy (Caddy in test, Apache in production) adds
Access-Control-Allow-Origin/Access-Control-Allow-Credentialsheaders to the/remote.php/webdav/path. See Switching to native WebDAV above. - Search page integration (
has_search_page) assumes the blog theme. - Comments require write access to the post/page file (they go through the serve.php write proxy). The comment form is hidden for everyone else; if visitor/reader comments are wanted, a dedicated sanitising comment-append endpoint is needed.
- When a user is moved between silos, the move tooling must delete the
user's
oc_files_picocmsrows on the old silo. The master row plus the lookup-through fallback keep the site URLs working on the new silo without any local rows, but a stale row on the old silo would make direct URLs to that silo serve a 404 instead of redirecting.
serve.php adds css/site-images.css (end of <head>) and js/site-images.js
(end of <body>) to every page, whatever the theme, so these work the same on
all sites — Markdown {.modal-image .small-image} or HTML
<video controls class="medium-image" src="clip.mp4">:
| Class | Effect |
|---|---|
.tiny-image |
at most 120 px |
.small-image |
at most 320 px (the Markdown editor's default for inserted images) |
.medium-image |
at most 640 px, centred on its own line |
.large-image |
the full width of the text |
.modal-image |
click opens the image full size (Escape or click closes) |
Being added after the theme's stylesheets, the sizes override a theme's own
definitions of the same names. The click-to-enlarge steps aside where a theme
has its own viewer: blog and team (a .modal element after each .modal-image)
and documentation (ekko-lightbox, which opens every image). Theme files are
untouched. Older class names some themes define (.smaller-image,
.narrow-image, …) keep working in those themes.