From 00c6658e6f677ace3d224abeb0a52fab2dc362ee Mon Sep 17 00:00:00 2001 From: Joachim Van Herwegen Date: Fri, 5 Aug 2022 08:08:34 +0200 Subject: [PATCH] docs: Update metadata documentation --- RELEASE_NOTES.md | 4 +++- documentation/markdown/README.md | 2 +- .../metadata.md} | 6 ++--- documentation/mkdocs.yml | 23 ++++++++++--------- 4 files changed, 19 insertions(+), 16 deletions(-) rename documentation/{metadata-editing.md => markdown/metadata.md} (94%) diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md index c6908ff14..e781a7453 100644 --- a/RELEASE_NOTES.md +++ b/RELEASE_NOTES.md @@ -9,7 +9,9 @@ - The CSS can now run multithreaded with multiple workers, this is done with the `--workers` or `-w` flag. - When starting the server through code, it is now possible to provide CLI value bindings as well in `AppRunner`. - The user can choose to "Log in with a different account" on the consent page -- Metadata of resources can now be edited by PATCHing its description resource. See the [documentation](./documentation/metadata-editing.md) for more information. +- Metadata of resources can now be edited by PATCHing its description resource. + This has an impact on which requests are allowed. + See the [documentation](https://communitysolidserver.github.io/CommunitySolidServer/4.0/s/metadata.md) for more information. ### Data migration The following actions are required if you are upgrading from a v4 server and want to retain your data. diff --git a/documentation/markdown/README.md b/documentation/markdown/README.md index 74696db99..94d1a1428 100644 --- a/documentation/markdown/README.md +++ b/documentation/markdown/README.md @@ -30,7 +30,7 @@ the [changelog](https://github.com/CommunitySolidServer/CommunitySolidServer/blo ## Using the server * [Basic example HTTP requests](example-requests.md) - * [Editing the metadata of resources](metadata-editing.md) + * [Editing the metadata of a resource](metadata.md) * [How to use the Identity Provider](identity-provider.md) * [How to automate authentication](client-credentials.md) * [How to automatically seed pods on startup](seeding-pods.md) diff --git a/documentation/metadata-editing.md b/documentation/markdown/metadata.md similarity index 94% rename from documentation/metadata-editing.md rename to documentation/markdown/metadata.md index cb5ea3503..53bfb56f5 100644 --- a/documentation/metadata-editing.md +++ b/documentation/markdown/metadata.md @@ -16,12 +16,12 @@ Clients should always follow this link rather than guessing its URL, because the Solid Protocol does not mandate a specific description resource URL. The default CSS configurations use as a convention that `http://example.org/resource` has `http://example.org/resource.meta` as its description resource. -This pattern can be changed in the [metadata configuration file](../config/util/auxiliary/strategies/meta.json). ## How to edit the metadata of a resource Editing the metadata of a resource is performed by editing the description resource directly. -This can only be done using `PATCH` requests (see [example workflow](#workflow)). +This can only be done using `PATCH` requests +(see [example workflow](#example-of-a-workflow-for-editing-a-description-resource)). `PUT` requests on description resources are not allowed, because they would replace the entire resource state, @@ -59,7 +59,7 @@ Container metadata can only be added and modified by performing a `PATCH` on the similarly to documents. This is done to clearly differentiate between a container's representation and its metadata. -## Example of a workflow for editing a description resource {#workflow} +## Example of a workflow for editing a description resource In this example, we add an inbox description to `http://localhost:3000/foo/`. This allows discovery of the `ldp:inbox` as described in the [Linked Data Notifications specification](https://www.w3.org/TR/ldn/). diff --git a/documentation/mkdocs.yml b/documentation/mkdocs.yml index bce1cb59a..72bd2deca 100644 --- a/documentation/mkdocs.yml +++ b/documentation/mkdocs.yml @@ -9,7 +9,7 @@ theme: - media: "(prefers-color-scheme: light)" scheme: default toggle: - icon: material/weather-night + icon: material/weather-night name: Switch to dark mode primary: deep purple accent: deep orange @@ -52,12 +52,12 @@ markdown_extensions: - pymdownx.tilde - pymdownx.details - pymdownx.highlight - - pymdownx.superfences + - pymdownx.superfences - pymdownx.smartsymbols extra: - version: + version: provider: mike social: - icon: fontawesome/brands/github @@ -70,20 +70,21 @@ extra: link: https://gitter.im/CommunitySolidServer/community nav: - - Welcome: + - Welcome: - README.md - - Usage: - - 'Example request': example-requests.md - - 'Identity provider': identity-provider.md - - 'Client credentials': client-credentials.md - - 'Seeding Pods': seeding-pods.md + - Usage: + - Example request: example-requests.md + - Metadata: metadata.md + - Identity provider: identity-provider.md + - Client credentials: client-credentials.md + - Seeding pods: seeding-pods.md - Architecture: - Architecture: architecture.md - Dependency injection: dependency-injection.md - - Contributing: + - Contributing: - Pull requests: making-changes.md - Releases: release.md - API: ./docs/" target="_blank -# To write documentation locally, execute the next line and browse to http://localhost:8000 +# To write documentation locally, execute the next line and browse to http://localhost:8000 # docker run --rm -it -p 8000:8000 -v ${PWD}/documentation:/docs squidfunk/mkdocs-material