Fediversity/Fediversity
12
1
Fork 3
Code Issues 22 Pull requests 2 Actions Projects 1 Activity

Matrix documentation #44

Closed
hans wants to merge 144 commits from hans/documentation into main
pull from: hans/documentation
merge into: Fediversity:main
Conversation 7 Commits 144 Files changed 30 +1892 -26
hans commented 2024-11-28 16:59:24 +01:00
Owner
Copy link

This is the documentation for building a Matrix server. The only things that should be different from main are under directory "matrix". Other changes/commits should already be in main.

This is the documentation for building a Matrix server. The only things that should be different from main are under directory "matrix". Other changes/commits should already be in main.
hans added 138 commits 2024-11-28 16:59:26 +01:00 
git-subtree-dir: matrix
git-subtree-mainline: 79b663f6d0
git-subtree-split: 0a991a5140
that directory will only grow
this allows writing the beginning of the indented string at the desired
indentation
with an example
it turns out that setting a value appends to that.
the default only needs to be overridden when the symbolic name of the
document changes. while there's a chance people will inadvertently break
links that way, it's requires less up-front knowledge to work with.
- links are constructed explicitly, relative to the current page's
location
- templates are called explicitly by output type
this is roughly sufficient to recreate the website as it currently is

- elements:
  - document
  - html
  - head
  - title
  - base
  - link (variants that must be unique nested under `head` directly)
    - canonical
  - meta (same as for link):
    - charset
    - viewport
    - author (can be multiple, but still unique in aggregate for a document)
    - description

- global attributes:
  - class
  - hidden
  - id
  - lang
  - style
  - title

- element-specific attributes:
  - href
  - target

there's still a lot to do for a reasonably complete implementation, most
importantly everything concerning
- navigation
- top-level flow content (`div`, `article`, headings, `p`, ...)
- stylesheets

there's also some infrastructure to be arranged for easy but somewhat
safe switching between literal HTML and structured representations.
this was quite a beast to tame, but it now allows putting sections anywhere
in the tree without having to redundantly specify heading levels, which
will be computed automatically from the nesting depth.

the whole thing will also blow up if the maximum section nesting depth
is exceeded, just as the spec requires - albeit with an absolutely
impenetrable error message. this could in principle be improved with
lots of additional machinery, but this is by far not low-hanging fruit.

just don't nest your sections too much.
the templates collection will soon only be there for reusable snippets,
while the HTML representation of document types will be attached to
those types directly.
- automatically assign heading levels
- check that the maximum nesting depth is not exceeded
this is practical for debugging and demonstration purposes
this allows adding files to the output as they are
this allows for more customised styling
it also features a dark mode
Merge branch 'main' into hans/documentation
All checks were successful
/ check-pre-commit (pull_request) Successful in 20s
Details
8c7ee15bcc
hans commented 2024-11-28 17:00:29 +01:00
Author
Owner
Copy link

I don't know how to do the cherry-picking, all I get is errors or an empty commit. All commits other than mine shouldn't be here.

I don't know how to do the cherry-picking, all I get is errors or an empty commit. All commits other than mine shouldn't be here.
hans commented 2024-11-28 17:03:30 +01:00
Author
Owner
Copy link

Forgejo's warning "this branch is out-of-date with the base branch" should probably be solved with "update branch by rebase". The history was changed early on in the life of this branch, so that gave me a whole lot of merge-conflicts.

Forgejo's warning "this branch is out-of-date with the base branch" should probably be solved with "update branch by rebase". The history was changed early on in the life of this branch, so that gave me a whole lot of merge-conflicts.
hans added 1 commit 2024-11-28 23:04:31 +01:00
Added important note about browsers.
All checks were successful
/ check-pre-commit (pull_request) Successful in 12s
Details
82ede35d89
hans added 1 commit 2024-11-29 02:25:41 +01:00
Added first bit of Draupnir documentation.
All checks were successful
/ check-pre-commit (pull_request) Successful in 12s
Details
3e63b4b837
hans added 1 commit 2024-11-29 02:27:10 +01:00
Table layout corrected.
All checks were successful
/ check-pre-commit (pull_request) Successful in 12s
Details
f72080a345
hans added 1 commit 2024-11-29 02:28:11 +01:00
Table layout corrected, again.
All checks were successful
/ check-pre-commit (pull_request) Successful in 12s
Details
8c89f277d6
hans added 1 commit 2024-11-29 02:29:20 +01:00
Table layout corrected, last time.
All checks were successful
/ check-pre-commit (pull_request) Successful in 11s
Details
ea79eb37c9
hans added 1 commit 2024-11-29 02:45:30 +01:00
Extra bit of Draupnir documentation.
All checks were successful
/ check-pre-commit (pull_request) Successful in 12s
Details
070209cbfa
ronny commented 2024-11-29 10:23:50 +01:00
Member
Copy link

I think this is a great and detailed overview of what we need to configure in these applications, the Debian way. Next step is to move these into a Nix-package.

I think this is a great and detailed overview of what we need to configure in these applications, the Debian way. Next step is to move these into a Nix-package.
hans commented 2024-11-29 16:08:57 +01:00
Author
Owner
Copy link

The idea is to create a few configuration that can easily be built for customers. Customers should be able to set a few checkboxes, enabling or disabling a few things.

This thing authorizes against LDAP, I assume that we want to offer OAuth2 and/or local passwords too. Moderation (working on that) isn't useful for every instance, but an absolute must-have for others.

The idea is to create a few configuration that can easily be built for customers. Customers should be able to set a few checkboxes, enabling or disabling a few things. This thing authorizes against LDAP, I assume that we want to offer OAuth2 and/or local passwords too. Moderation (working on that) isn't useful for every instance, but an absolute must-have for others.
hans changed title from WIP: Matrix documentation to Matrix documentation 2024-11-29 16:18:03 +01:00
Niols commented 2024-11-29 17:01:40 +01:00
Owner
Copy link

I will fix the Git history quickly.

I will fix the Git history quickly.
Niols commented 2024-11-29 17:21:51 +01:00
Owner
Copy link

@hans> Can you take a look at hans/documentation-fixed? I checked and there is not a single difference when it comes to the matrix/ directory, and the history looks cleaned.

If you're happy with it, you can pick it up as it is, but it's probably nicer if you rebase those commits so as to sign them yourself. (Btw, if you like signing your commits, you could inform Forgejo of your key such that they appear as verified, now they only appear as signed.) And then just reset hans/documentation from hans/documentation-fixed and force push here and everything should be pretty!

@hans> Can you take a look at `hans/documentation-fixed`? I checked and there is not a single difference when it comes to the `matrix/` directory, and the history looks cleaned. If you're happy with it, you can pick it up as it is, but it's probably nicer if you rebase those commits so as to sign them yourself. (Btw, if you like signing your commits, you could inform Forgejo of your key such that they appear as verified, now they only appear as signed.) And then just reset `hans/documentation` from `hans/documentation-fixed` and force push here and everything should be pretty!
hans commented 2024-12-02 10:07:02 +01:00
Author
Owner
Copy link

@Niols Looks good to me, thanks! New PR is in #46.

@Niols Looks good to me, thanks! New PR is in #46.
hans closed this pull request 2024-12-02 10:07:03 +01:00
All checks were successful
/ check-pre-commit (pull_request) Successful in 12s
Required
Details

Pull request closed

This pull request cannot be reopened because the branch was deleted.
Sign in to join this conversation.
Reviewers
No reviewers
Labels
Clear labels   
blocked

   
project-management

Project management related tasks

  
question
No labels
blocked
project-management
question
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
3 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference: Fediversity/Fediversity#44
No description provided.
Delete branch "hans/documentation"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?