[Epic] OpenCloud Conflu

[dragotin]

This describes an idea, and is a call for comments. It is still a draft.

OpenCloud Conflu

Conflu is a Confluence like system based on Markdown files embedded in OpenCloud. It can be enabled as extension.

The basic idea is that any file subtree in OpenCloud can be used for structured and nicely rendered documentation. Once a directory contains a conflu-root-file as decribed below, this directory and its children are considered to be conflu-files or resources.

The OpenCloud Web Client switches into a special view mode for these dirs, and renders Markdown files into html which are displayed in the Web Client instead of the file view.

Additionally, the Web Client displays management tooling to for example create a new pages or copy existing ones. It also offers an Edit-Button that opens an WYSIWYG editor on the currently displayed page that allows easy editing.

The file tree acts as tree in which the conflu pages are organized in.

With OpenClouds standard features such as versioning, sharing, taggung and access control, this will be a fully sharable, collaborative documentation system with a very low entry barrier and fun to work with.

Concept

The Conflu Root File

Any directory in OpenCloud can contain a conflu-Root-File with file extension rocc (for root open cloud conflu). That file is the indicator that the directory contains markdown files (extension *.md) which should be rendered for easy reading and presented coherently by OpenCloud as documentation.

If a root file is found in the directory, the web client displays the rendered page based on the file content.

{
    "Conflu": {
        "title": "Company Handbook",
		"css": "handbook.css",
		"template": "conflu.tmpl",
		"TOC": {
            "enabled": "true",
			"template": "toc.tmpl"
        }
    }
}
    

Side Bar

Each page should render a sidebar, which can contain a Table of Contents of all files in the directory as well as sub folders which might contain more files. It also can contain useful other information about the actual file or the entire documentation tree.

Non Web Clients

Mobile clients just display the rendered version of the conflu pages in the first iteration. Later, editing might be feasible.

The desktop client just treats the directory "as is" and just syncs the raw files without rendering. Later there might be a desktop variant of the entire view- and editing system.

[butonic]

I would prefer to use README.md files for this. In the first step web could just check if a readme file exists and render that below (or above) the document.

To make things more fancy Markdown files can have a front matter that contains metadata:

---
date: 2025-05-27T21:53:54+02:00
draft: false
params:
  author: John Smith
title: Example
---
# Heading 1
## Heading 2
### Heading 3
wooo

This mechanism is also used by jekyll, hugo ... and hell, there is even a CMS called Front Matter

Web could use the front matter to change the default view to a 'conflu' view? The frontmatter could indicate where to render the file list: above/top, below/bottom, hidden ... dunno ...
from there on the standard hugo or jekyll diecrtory layout could be used ... we could even put configuration for a static sit generator in there ... or maybe just stick to what jekyll and hugo are doing?

We could even add our own conflu property to mix it with any other tool using markdown frontmatter:

---
date: 2025-05-27T21:53:54+02:00
draft: false
params:
  author: John Smith
title: Example
conflu:
  title: "Company Handbook"
  css: handbook.css
  template: conflu.tmpl
  toc:
    enabled: true
    template: toc.tmpl
---
# Heading 1
## Heading 2
### Heading 3
wooo

[fschade]

https://github.com/WordPress/gutenberg

[dragotin]

I wonder if https://astro.build/ or Frontmatter https://frontmatter.codes/docs/markdown can help us