1. Project Overview & Quickstart (owncloud/prepared-npm-commands)
prepared-npm-commands
Open-source repository owncloud/prepared-npm-commands
Repository Details
- Repository: owncloud/prepared-npm-commands
- Primary Language: Code
Note: High-volume repository documentation is actively indexed and synchronized by YakaAI.
2. Official Technical Reference & Guides (owncloud/docs)
File: README.md
⚠️ This repository is archived and no longer maintained.
It is read-only and will not receive further updates or contributions.
ownCloud Documentation
The central Antora-based documentation site for all ownCloud products. This repository contains the site playbook (site.yml), Antora and AsciiDoc extensions, shared resources, fonts, and build scripts that aggregate content from all docs-* component repositories into a single published documentation site at doc.owncloud.com.
Getting Started
Install dependencies and build the documentation locally:
npm install
npm run antora-local
npm run serveThis builds the site to public/ and serves it at http://localhost:8080.
Documentation
Part of ownCloud Documentation
This is the top-level documentation build repository. It pulls content from component repositories such as docs-server, docs-ocis, docs-client-desktop, and others. The published site is available at doc.owncloud.com.
Community & Support
Star this repo and Watch for release notifications!
Contributing
We welcome contributions! Please read the Contributing Guidelines
and our Code of Conduct before getting started.
Workflow
- Rebase Early, Rebase Often! We use a rebase workflow. Always rebase on the target branch before submitting a PR.
- Dependabot: Automated dependency updates are managed via Dependabot. Review and merge dependency PRs promptly.
- Signed Commits: All commits must be PGP/GPG signed. See GitHub's signing guide.
- DCO Sign-off: Every commit must carry a
Signed-off-byline:textgit commit -s -S -m "your commit message" - GitHub Actions Policy: Workflows may only use actions that are (a) owned by
owncloud, (b) created by GitHub (actions/*), or (c) verified in the GitHub Marketplace.
Security
Do not open a public GitHub issue for security vulnerabilities.
Report vulnerabilities at https://security.owncloud.com -- see SECURITY.md.
Bug bounty: YesWeHack ownCloud Program
License
This project is licensed under the AGPL-3.0.
About the ownCloud OSPO
The Kiteworks Open Source Program Office, operating under
the ownCloud brand, launched on May 5, 2026, to steward the open source
ecosystem around ownCloud's products. The OSPO ensures transparent governance, license compliance,
community health, and sustainable collaboration between the open source community and
Kiteworks, which acquired ownCloud in 2023.
- OSPO Home: https://kiteworks.com/opensource
- GitHub: https://github.com/owncloud
- ownCloud: https://owncloud.com
For questions about the OSPO or licensing, contact [email protected].
License Migration to Apache 2.0
The OSPO is driving a strategic relicensing of ownCloud repositories toward the
Apache License 2.0, following
the Apache Software Foundation's third-party license policy.
Individual repositories will migrate as their audit is completed. The LICENSE file
in each repo reflects its current license status (not the target).
Current license: AGPL-3.0 (Category X per Apache policy -- cannot be included in Apache-2.0 works).
Migration prerequisites for this repository:
- CLA/DCO coverage: All past contributors must have signed agreements permitting relicensing
- Copyleft dependency audit: All AGPL/GPL dependencies must be replaced or isolated
- KDE heritage review: Any code with KDE-era copyrights requires legal analysis
- Complete relicensing: AGPL-3.0 is a strong copyleft license; migration requires full relicensing of all files, not just a header change
File: docs/antora-site-structure.md
Antora Site Structure for Docs
Table of Contents
- Why Antora
- Scope of Documentation Repositories
- Scope of Content Accessibility
- Structure of Directories
- Scope of Antora Definitions
- The Antora UI Template
Why Antora
The main reasons for using Antora are the following:
It uses and extends the asciidoc text writing format.
- As an example, defining tables is so much easier in asciidoc compared to using markdown.
- Using attributes (variables), which scope can be easily determined, content can be dynamically defined.
It extends asciidoc with multi-repo capabilities. This is done in a way where any issues identified can be easily tracked down to the source where this happens.
The doc writer does not need to care about repos, or content locations, etc. anymore as this is virtualized by Antora and content can be accessed in a standardized way via Resource ID Coordinates.
You can easily extend functionalities with extensions added via
site.yml.Antora distincts writing the documentation and the UI-Template defining how the content is presented. This is also done in a way where any change can be tracked down to its source.
Scope of Documentation Repositories
The ownCloud documentation consists of a building repo named docs which has NO content and additional repos like ocis or the clients which are included as content sources defined in site.yml.
Our setup is made in a way, where each repo can build it's own content individually for local testing and checking validity. Only the build of the docs repo creates documentation which is pushed to the web. There is one exception, when reenabled, PDF's are created AND pushed via the CI from the content source where it applies.
Note that the docs-main repo only contains the entry page but no detailed product description.
repo content source
docs --> docs-main
docs-ocis
docs-client-desktop
docs-client-ios-app
docs-client-android
...Note that the arrow from docs repo to a content source is intentionally unidirectional in our setup and should be respected. See more details about the reason below.
Scope of playbook files (site.yml)
In general, only one site.yml file is neccessary building the complete site. This site.yml file is located in the docs repo. Additionally, we have for each content source its own site.yml for local building, development and testing purposes only. The scope of these local site.yml files are restricted to the respective content source and any definitions made in these are not availabe outside.
Note that this behaviour is relevant for the playbook site.yml files only and does not apply to the component descriptor files antora.yml in each content providing repo!
Scope of attributes (site.yml)
With the use of the load-global-site-attributes extension, common attributes are not needed to be maintained for each repo individually. These attributes are defined in the docs repo and are, if defined in the content providing repo, sourced from there. In addition, if necessary, you can re-define attributes in a repo which will then overwrite global attributes if exists. This makes local building very comfortable. You can also source for testing 'global' attributes from a local file instead loading it from docs.
If there are any global attributes that need to be updated after a merge of a particular content repo, an additional PR in the docs repo needs to be created to make that change globally available.
Scope of Content Accessibility
Because Antora is capable of defining additional content sources, you can access content from these resources. The setup is flat, no main/child environment. To access resources, follow the Resource ID Coordinates scheme.
IMPORTANT:
The following scheme will be bidirectional and restrictions will go away when updating to Antora 3.2 and using the Antora Atlas extension which will provide a content manifest.
Because of the setup we have made regarding testing, the direction of the arrow is important.
Possible
docs --> docs-client-ios-app
└> index.adocThis docs master repo can access content from any content source (like docs-client-ios-app) and vice versa at build time , because docs has referenced the repo and made it available as content source to all.
Impossible
docs-client-ios-app --> docs-client-desktop
└> index.adoc
docs-client-ios-app --> docs
└> index.adocWhen doing a build of a content source (like the docs-client-ios-app) which is neccesary for testing purposes, any references to another content source or to docs will fail as the referenced content source is unknown. Those references will throw an error/warning. Even if it is not the best approach, use .html references to any other source outside the working repo.
With a futuer release of Antora, it will be possible to use a kind of map to make references in local repos at build time which are not physically included and would return errors or warnings otherwise.
Structure of Directories
All doc repositories have an identical directory structure. This helps maintaining and accessing content easily.
The Antora Directory Structure
modules/named-module-1/attachment
/examples
/images
/pages
/partials
/named-module-2/attachments
/...
/...Please see Standard File and Directory Set at Example 1 for details.
Note that there is one important exception:
The navigation file nav.adoc is under the partials directory and not at the level of the named-module (like ROOT or admin ect). This is necessary because only files which are in a family directory can be accessed from outside. This means docs can access e.g. nav.adoc at any content source like docs-client-ios-app.
Other Necessary Directories
Beside the necessary directories for node, other important directories are:
bin/ Helper scripts to maintain the documentation
book_templates/ Template file(s) to create the pdf file
ext-antora/ Antora extensions necessary for the build process
ext-asciidoc/ Asciidoc extensions necessary for the build process
pdf_web/ Output directory of generated pdf files, currently unused!
public/ Output directory of generated html files, only used locally!
resources/ Themes necessary for creating pdf files, currently unused!
tmp/ Temp directory used for htmltest (broken link checking)Important Files
The following files are important to run a build properly.
Note that Node related stuff is not mentioned explicitly:
.drone.star Define the build process steps when triggered by a PR
package.json Define the antora environment and scripts to run at the cli
antora.yml Contains definitions and attributes that only belong
to the respective component (version dependent!)
site.yml Global site definitions, attributes defined overwrite global ones
global-attributes.yml The file containing global attributes used by the extension.
Mandatory for the docs repo, optional otherwise (version dependent!)Scope of Antora Definitions
Versioning
While you can read more details about What is antora.yml? and What is site.yml (the playbook), here are some important items:
To manage versions in docs, we use branches. This means that any content based on a variable (attribute) limited to a branch must go into the component description file antora.yml and be maintained accordingly. Any attribute that is used in any branch of any component must be defined in the global-attributes.yml in the docs repo.
Accessibility and Availability of Attributes
- The scope of attributes defined in a page is limited to that page only.
- The scope of attributes defined in
antora.ymlis limited to the branch and component where it is defined. This is also true for attributes that should be accessed from the UI-Template. - The scope of attributes defined in
site.ymlincluding defined via theglobal-attributes.ymlfile are global. The term global has two flavours in our setup:- When used in the building repo
docs, it becomes available to all sources at any time. - When used in a content source, it is only availabe to the content source during a local test build.
- When used in the building repo
- Attributes starting with
page-are also available to the UI-Template when running a build. The rules above apply. This is important when defining UI content based on attributes. To access these attributes in the UI-Template usepage.attribute.namewherenameis without leadingpage-For details see AsciiDoc Attributes in Antora.
IMPORTANT
If used attributes are not defined during build time, Antora hard stops and files an error. You must fix those issues BEFORE creating the PR - else it never will get green. Also see the CI log for details.
The Antora UI Template
As described on top, Antora separates the writing of text and the presentation design. Our presentation design is defined in the docs-ui repository. Any change made in the UI affects the complete documentation, careful tests are mandatory.
File: docs/best-practices.md
Best Practices and Tips
This page gives contributors a quick overview of tips and best practices for
writing in AsciiDoc. It is for sure not complete nor covers all possibilities, but gives a quick
reference for common used writing and formatting tasks. For a complete reference see the
Asciidoctor Documentation.
Also see the AsciiDoc Syntax Quick Reference
guide.
Table of Contents
- Initial Reading
- File Locations
- Links
- Images
- Include
- Table of Contents
- Code Blocks
- Literal Text and Blocks
- Attributes
- Admonition
- Air Quotes
- Preserve Line Breaks
- Text Formatting
- Keyboard Shortcuts and UI Button Text
- Menu Selections
- Lists
- Headers, Titles, Sections, Anchors and Paragraph Titles
- Tables
- Conditional Rendering
- TabSets
- Comments
- Relocating or Renaming Files
Initial Reading
Here is a good starting point to get a quick Antora overview Three Core Antora Concepts
File Locations
- All documents are written into the directory
modules/module_name/pages/`` - All images are written into the directory
modules/module_name/assets/images/`` - All examples are written into the directory
modules/module_name/examples/``
When using paths to include, you might need to use the module_name when linking to another module,
but you must not use pages, assets/images or examples as the path component, only ``.
See the examples in the relevant sections.
Links
In a nutshell, there are two kind of links.
- External links (referencing content outside the documentation)
- Internal links (referencing content inside the documentation)
External Links
Reference: Links
A link follows this style: http(s)://domain/#section[Printed Name]
Where #section and [Printed Name] are optional components.
The link: prefix is only needed when the target is not a URI. That's because the URI protocol is an implicit
macro (in other words, http(s): is recognized as a macro prefix of an implicit link).
Example: https://github.com/owncloud-docker/server#launch-with-plain-docker[in the GitHub repository]
A URL may not display correctly when it contains characters such as underscores (_), carets (^) or double quotes (")
Please see Troubleshooting Complex URLs how to solve that.
This is an example of an URL containing problematic characters which needs special treatment:https://www.owasp.org/index.php/Cross-site_Scripting_(XSS)
Strongly in favour of using attributes which greatly improves readability while authoring the document.
= The Page Header
:internal-link-name-url: https://example.com/content/link_can_be_very_long
Text {internal-link-name-url}[highlighted text] text.For the special case when the URL also contains double quotes ("), you must additionally replace them manually with %22 (utf-8 encoding) in the attribute used.
It is important that :internal-link-name-url: is placed directly below the page header.
Any number of these link attributes can be added. Without being mandatory, it has turned
out as a matter of good practice to end your link name with -url.
NOTE If you want to prevent automatic linking of a URL, prepend it with a backslash (\).
This will create text but not a clickable link and can be used for example URLs.
This method helps prevent false positives when checking broken links.
Example:
This is an example of an unlinked web address: \http://example.comThe above example renders as: This is an example web address: http://example.com
but there is no link.
See Troubleshooting URLs for more possibilities.
Internal Links
Prefix: xref:
Reference: Cross Reference
In a nutshell, an internal link called Cross Reference can link to
- an in-page reference
- a documentation file
- a section title or anchor name inside a documentation file
All content you want to reference must be inside the directory structure of modules/.
An xref is usually written in the following example style:xref:module_name:/file.adoc#section[Printed Name]
Where module_name:, #section and [Printed Name] are optional components.module_name: is mandatory when referenced content is not in the same module.
`` is the relative path via the module name to your referenced file.
You can reference a section or an anchor inside the same file, another file - even in another module.
Section titles automatically create references, where the text is converted to lower case characters
and all special characters including an underscore are converted to a dash (_)
You can create anchors manually anywhere in the page by using following methods:
- text
[#anchor-name]text (anchor-name will not be printed, it is only the reference point) - text
[#anchor-name]#Anchor text to be referenced to#text (Anchor text will be printed)
Reference Examples:
This example references a section title inside the same document:
xref:section-title[FAQ]This example references a manual anchor inside the same document:
xref:anchor-name[FAQ]This example references another file:
xref:configuration/server/occ_command.adoc[Market app]This example references another file and a particular section title:
xref:configuration/server/occ_command.adoc#apps-commands[Market app]This example references another file in another module and a particular section title:
xref:admin_manual:configuration/server/occ_command.adoc#apps-commands[Market app]
Strongly In general it`s advisable to use a ToC (Table of Contents) instead of a list of xref´s.
Note: Use a link checker regularly to find broken links to section titles or anchors.
If an anchor link is broken, a build will not report an error as the page itself is accessible.
Images
Prefix: image
Reference: Images
All images have to be stored in a path under modules/module_name/assets/images/``
An image is written in following example style: image:/image_name[Alternative Image Text, options]
Please use the comma as separator for one or more options.
The , options part is optional. Here you can define e.g. the sizing of an image like , width=40%
Example: image:configuration/files/encryption1.png[Encryption]
There are two ways that an image is treated defined by either using image: or image::
When using image:, the image will be part of the text written. This is useful when you want to have
an image part of the text flow like an icon you reference to.
When using image::, the image is not part of the text written and stands on its own. This means it
will be rendered into a new line and be centered by default if not otherwise defined by an option likealign="center|left|right"
IMPORTANT
Please be advised, in case you use an Alternative Image Text, not to use double quotes to highlight some text elements.
Double quotes will be rendered properly when the html documentation is built, but creating the pdf will return
a warning that the string can not be parsed and the complete image link is broken.
You can avoid that by using single quotes and ticks (not backticks!) instead.
Bad:image:enterprise/firewall/firewall-3.png[Protecting files tagged with "Confidential" from outside access]
Good:image:enterprise/firewall/firewall-3.png[Protecting files tagged with 'Confidential' from outside access]
Include
Prefix: include
Reference: Include
The include directive provides a way to import content from another file into the current document.
An include is written in following example style: include::/file[<attrlist>]
When using asciidoc files to include, the <attrlist> option contains as example the leveloffset=+1 to correct the level offset of the file included.
You can include example files like scripts or include documentation files.
Both types are used to make the raw documentation files easier to read and to maintain.
Example Files Like Scripts
When creating example files, these files must be saved into a path of the examples directory: module_name/examples
The directive consists of following components:include::{examplesdir}<additional-path>/file.ext[]
Example:
include::{examplesdir}installation/post-installation-steps.sh[]
{examplesdir} will be resolved by the build process automatically
Example Files of Type `asciidoc`
If you include a standard page (a page that is stored in the pages directory) into another page, you must set the page-partial AsciiDoc attribute in the document header of the page being included.
= The Page Header
:page-partial:
Page contents.Example:include::encryption-types.adoc[leveloffset=+1]
(the including file in this example is in the same directory as the included file)
Table of Contents
Prefix: toc
Reference: Table of Contents (ToC)
A table of contents (ToC) is, if not otherwise defined, an index of section and subsection
titles that can be automatically generated from the pages structure when converting a
document with Asciidoctor.
The easiest way of adding a ToC is shown in the following example.
= The Page Header
:toc:
Page contents.Please also see additional directives like:toc-title,toclevels or
In-Document Placement
IMPORTANT All attributes of kind :name: must be direct under the page header without blank lines.
Code Blocks
Reference: Listing and source code blocks
Reference: Building blocks in AsciiDoc
[source,<language>]
----
text
text
----Optional define the <language>
Example:
[source,bash]
----
subscription-manager repos --enable rhel-server-rhscl-7-rpms
----You can also use include in code blocks to include an example.
Example:
[source,bash]
----
include::example$installation/post-installation-steps.sh[]
----- Use
plaintextfor all examples not belonging to any language as this will properly trigger css. - Note that you can copy a source block by clicking the copy symbol to the right of the example without the bash prompt if one is present.
IMPORTANT For highlighting bash commands properly, you need to distinguish between console and bash as source language:
- Use
consolewhenever there is a bash prompt with one of the following prompt characters> % $ #where there can also be up to 3 whitespaces before the bash prompt, or a bash prompt like[test@ubuntu~]$. The bash prompt will be visible, rendered differently but can't be selected with the mouse manually.bashcommands after the bash prompt will be highlighted. Note that if there is no bash prompt upfront, no highlighting will take place! - Use
bashwhenever there is no bash prompt upfront and you either show shell commands or bash scripts.
OCC Examples
When creating examples that show how to use occ, ensure that you use the occ-command-example-prefix attribute.
Doing so will keep all examples of its use consistent throughout the documentation.
Note: when used within a source code block, as in the following example, subs="attributes+" has to be set, otherwise it won't render properly:
[source,bash,subs="attributes+"]
----
{occ-command-example-prefix} -h
----This will print out the following when rendered in the docs:
sudo -u www-data occ -hLiteral Text and Blocks
Reference: Literal Text and Blocks
Literal paragraphs and blocks display the text you write exactly as you enter it. Literal text is treated as pre-formatted text.
Example:
....
Checking system health.
- file permissions are ok.
....Attributes
Reference: Document Attributes
Reference: Inline Passthroughs
Attributes are a way of creating a variable with content which then can be used throughout the document. Using attributes increases
readability a lot and makes it easy to change content one time for all locations used. Attributes are written on top of the page
and have the following form:
Definition:
:name-of-an-attribute: valueUsage:
This is some text {name-of-an-attribute} which continues here.Attributes can also be used in scripts when you want to handover common used values. In this case, you must define the attributes and macros that
are handed over to the script for processing. "macros" is e.g. needed, when using inline passthroughs:
[subs=attributes+,+macros]
----
include...
----When you have parts of texts or inside a script where you must render the content as it is, which is necessary for e.g. language constructs,
read the Antora Inline Passthroughs section referenced above.
Admonition
Reference: Admonitions
Reference: Admonition blocks
An admonition paragraph is rendered in a callout box with the admonition label — or its corresponding icon — in the gutter.
Asciidoctor provides five admonition style labels: NOTE, TIP, IMPORTANT, CAUTION and WARNING
Simple Admonitions
Use this way when you just have to write text.
A simple admonition is written in the following style: <label>: Text
Example:
NOTE: If you have a large ownCloud installation and have
shell access, you should ...Complex Admonitions
A complex admonition can contain special formatting, tables, lists, literal text and blocks
and is written in the following style, where ==== define the begin/end of the admonition block:
[<label>]
====
your complex text
====Example:
[TIP]
====
We strongly encourage you to put your server in single user mode before setting up encryption.
To do so, run the following command:
....
sudo -u www-data occ maintenance:singleuser --on
....
====Air Quotes
Reference: Air Quotes
If you want to quote sentences or statements but not using an admonition, you can use air quotes.
Air quotes are two double quotes on each line, emulating the gesture of making quote marks with two fingers on each hand.
Example:
""
Not everything that is faced can be changed.
But nothing can be changed until it is faced.
""Preserve Line Breaks
Reference: Line Breaks
Since adjacent lines of text are combined into a single paragraph, you can wrap paragraph text or put each
sentence or phrase on a separate line. The line breaks won’t appear in the output.
If you want the line breaks preserved, use a space followed by the plus sign +.
You can use this method also in tables or lists.
Example:
This is the first line, +
This is the next line separated by a line break.Text Formatting
Reference: Text Formatting
There are various ways to emphasize text.
You can use styles like bold, italic, etc respectively quote text.
If you want to print a tick or backtick or curly brace etc as it is, you must escape it. Note, that if you want to print a full string without blanks in between like {my_text}, you only need to escape the first curly brace \{my_text}
Please see the reference link for more details.
Keyboard Shortcuts and UI Button Text
Reference: Keyboard Shortcuts
Reference: UI buttonss
You can create a button styled text like you want a user to press specific keyboard button(s) or browser text buttons.
The syntax for keyboard shortcuts is: kbd:[key(+key)*]
The syntax for UI button text is: btn:[text]
Examples:
kbd:[F11]
kbd:[Ctrl+T]
kbd:[Ctrl+Shift+N]
kbd:[Show disabled apps]
btn:[OK]
btn:[Open]Menu Selections
Reference: Menu Selections
IMPORTANT You must set the :experimental: attribute to enable the UI macros.
Trying to explain to someone how to select a menu item can be a pain. With the menu macro, the symbols do the work.
The syntax for this is: menu:start[next > next > *]
Example:
Go to menu:Settings[Admin > Apps] and click on kbd:[Show disabled apps]Lists
Reference: Unordered Lists
To create a list, use the * sign.
You can give your list a title by adding on top of the list a . directly followed by the text without a space.
If you want to nest your list, use multiple * stars according the nesting level.
When items contain more than one line of text, leave a blank line before the next item to make the list easier to read.
If you want to add additional paragraphs or other block elements, see List Continuation for more details.
Example:
.List Title
* level 1
** level 2
*** level 3
**** level 4
***** level 5
* level 1For creating complex list content, such as adding code blocks to a list element, use the following formatting to keep the content correctly linked to the list element:
.Add a source code block as part of a list element's content.
* list header
+
--
Your description text for the following command:
[source,console]
----
sudo service apache2 restart
----
NOTE: You MUST run this command with sudo previleges
--Headers, Titles, Sections, Anchors and Paragraph Titles
IMPORTANT Please use title case
for titles and sections.
Good: Examples of Title Case
Bad: Examples of title case
Headers
Reference: Header
The document header is a special set of contiguous lines at the start of the document that encapsulates the document title, author and revision information, and document-wide attributes (either built-in or user-defined). The header typically begins with a document title
Titles
Reference: Titles
The document title resembles a level-0 section title, which is written using a single equal sign = followed by at least one space, then the text of the title. The document title must be the first level-0 section title in the document. The only content permitted above the document title are blank lines, comment lines and document-wide attribute entries.
Sections
Reference: Sections
Sections partition the document into a content hierarchy. A section title represents the heading for a section. Section title levels are specified by two to six equal = signs. The number of equal signs in front of the title represents the nesting level (using a 0-based index) of the section.
INFO Sections automatically create a referencable anchor.
Section numbering should be in single steps. This means you will get a warning when using = and then ===.
Example:
= Document Title (Level 0)
== Level 1 Section Title
=== Level 2 Section TitleIf a page TOC (table of content) is defined, section levels are part of the TOC if the TOC setting includes the section level. In the rare case you want to exclude a section from the TOC but keep its referencability, add [discrete] right over the section.
Example:
= Document Title (Level 0)
:toc:
:toclevels: 3
== Level 1 Section Title
[descrete]
=== Level 2 Section TitleAnchors
Note: please check for documentation build warnings or use a broken link checker for broken references to anchors!
Referencing Sections with xref
Each section is by design its own reference ID called an Anchor which can be referenced with xref in the same or from another document. You can also give the section an own custom ID.
When using Auto-generated IDs some rules apply:
Compared to AsciiDoc's standard, ownCloud has set its own definition:
- All characters are converted to lowercase
- Spaces, hyphens, and periods are substituted by a dash
-
Example:
xref:my-section[Text to Print]
text
== My Section
textWhen using Custom IDs, those replace the auto-generated once. These are very useful when you want to define a stable anchor for linking to a section using a cross-reference. The benefit of using custom ID's is, that xref is independent of section text changes which can cause broken links.
Example:
xref:custom_id[Text to Print]
text
[[custom_id]]
== My Section
textUsing Anchors Independent of Sections
Reference: Defining an Anchor
In the same way creating a custom ID (anchor) for sections, you can create an anchor at any location you want to reference to.
Example:
xref:custom_id[Text to Print]
text
[[custom_id]]
textParagraph Title
Reference: Paragraph Title
You can assign a title to any paragraph, list, delimited block, or block macro.
In most cases, the title is displayed immediately above the content.
If the content is a figure or image, the title is displayed below the content.
The title text is rendered in a more visible style and the intention is usually to
highlight the following paragraph inside a section.
INFO Compared to sections, a paragraph title does not create a referencable anchor.
A block title is defined on a line above the element. The line must begin with a dot (.)
and be followed immediately by the title text.
Example:
.Title for this Paragraph
Text or lists or...Tables
Reference: Tables
Tables are delimited by |=== and made up of cells.
Cells are separated by a vertical bar |.
There are many ways to create and format tables, please see the reference for more details.
You can also take a look to already created tables in the documentation.
Example with defining table and cell width size plus the use of headers:
[width="80%",cols="30%,70%",options="header"]
|===
| Header of column 1 | Header of column 2
| Cell in column 1, row 1 | long Cell in column 2, row 1
| Cell in column 1, row 2 | long Cell in column 2, row 2
| Cell in column 1, row 3 | long Cell in column 2, row 3
|===This example shows that columns can also be written underneath:
[width="90%",cols="20%,80%",options="header",]
|===
| Directory
| Description
| `data//files_encryption`
| Users’ private keys and all other keys necessary to decrypt the users’ files.
| `data/files_encryption`
| Private keys and all other keys necessary to decrypt the files stored on a system wide external storage.
|===If you want to use block-level content in cells, such as a block image, you need to set the
cell type to a, short for "asciidoc", which treats it as a standalone AsciiDoc document.
[cols=",,",options="header"]
|===
| Classic theme
| Dark theme
| Light theme
a| image:themes/classic.png[ownCloud iOS App - Classic theme]
a| image:themes/dark.png[ownCloud iOS App - Dark theme]
a| image:themes/light.png[ownCloud iOS App - Light theme]
|===You can also align content in cells. Without the following directives, cells are always aligned
top/left. You can set the alignment for complete columns or individual cells. The style for the
alignment is always horizontal dot vertical. The dot separates the horizontal and vertical directive.
Examples:
^ center only, top automatically
^.> center, bottom
.> left automatically, bottomDirectives horizontal and vertical
`^` center center
`<` left top
`>` right bottomTo use these directives, you can either set them into the cols="" definition which is then used for all
columns like cols="^,^.>" or at the beginning of an individual cell ^.>| cell text.
If you want to make a headline above a table which does not render as table headline, you need to mark the headline accordingly. To do so, see the following example:
[caption=]
.Following will render as headline and not as "Table 1. Following..."
[width="50%",cols="40%,50%",options="header"]
|===
...Conditional Rendering
References: Conditionals
Antora can render conditionally. This is e.g. needed, when content can be rendered to html but not to pdf.
In these cases, you have to use a conditional render directive which renders content based on an attribute
which defines the type to be rendered. ownCloud has created predefined site wide attributes for this
case when the documentation is built for html or pdf.
ifeval::["{format}" == "html"]
...
endif::[]or
ifeval::["{format}" == "pdf"]
...
endif::[]TabSets
ownCloud has added the AsciiDoc tabset extension for the documentation. With tabsets, you can create tabs inside
your document which is very useful, for example, for scripts in different languages for the same task.
Attention: TabSets, by nature, cannot be rendered in pdf. You have to use conditional rendering and an own
description for html and pdf.
[tabs]
====
Tab A::
+
--
Tab A contents
--
Tab B::
+
--
Tab B contents
--
====Comments
Reference: Comments
If you want to add a single line comment in your page to remark a writers note which will not be rendered, use two consecutive slashes //
Example:
// Needs revision as a new release will change the parameter.If you want to comment a block, put the block between four slashes ////
Example:
////
Needs revision as a new release will change the parameter.
Maybe complex to do but lets see.
////Relocating or Renaming Files
The following procedure is necessary to optimize search engines (SEO).
This method will help with updating search engine results over time.
In case you relocate a page to another physical location, or you rename a page,
you have to do two things:
- Correct the path in the navigation
- Add a
:page-aliases:attribute in the document moved
The page-alias attribute, which you can see in the example below, lists one or more pages that
redirect to the current page. This attribute is given one or more AsciiDoc files that will redirect
to the current page.
Example:
= Page Title
:page-aliases: upgrade/service/apache.adocFile: docs/build-the-docs.md
Building the Documentation
Table of Contents
Install the Prerequisites
Before you can build the ownCloud documentation, you need to install the following software:
Checking for the Prerequisites on Linux
To check if they are installed on a Linux system, run the following command:
dependencies=( curl git node npm ruby ) && for i in "${dependencies[@]}"; do command -v $i; done;You will see the path to each binary displayed, if it is installed. For any that you do not see displayed, follow the instructions below to install it. This is an example output if you have everything installed. Please consider that the home directory, root in this example, is dependent on the user you used during installing and can be different in your installation.
/usr/bin/curl
/usr/bin/git
/home/<your-user>/.nvm/versions/node/v18.20.4/bin/node
/home/<your-user>/.nvm/versions/node/v18.20.4/bin/npm
/usr/bin/rubyInstall Prerequisites
If one or more of these commands reports an error, then that prerequisite is not installed. For any prerequisite that is not installed, follow the instructions below to install it.
curl
To install curl, which may not be present on a fresh installed OS, run the following command:
sudo apt install curlgit
To install git, download and install the git package for your operating system, or use your package manager if you are using Linux.
Ruby
To install Ruby, enter the following command:
sudo apt update
sudo apt install ruby-fullAfter the installation completes, check the installed Ruby version by executing the following command:
ruby --versionNode
While you can install Node from the official packages, we strongly recommend that you use NVM (Node Version Manager) to install and manage Node. Follow the NVM installation instructions to set up NVM on your machine. Once you've installed NVM, use a terminal and install a Node LTS version:
The following gives you an output of the latest available LTS versions.
nvm ls-remote | grep "Latest LTS"
v4.9.1 (Latest LTS: Argon)
...
v18.20.8 (Latest LTS: Hydrogen)
v20.10.0 (Latest LTS: Iron)Then install a suitable LTS version. You can install as many versions as you like or need, see example below.
nvm install 18.20.4List the installed versions
nvm ls
v18.20.8
v20.19.5
-> v22.19.0
system
default -> 22.19.0 (-> v22.19.0)
...Info:
The backend to push to the web uses node v18, see the .drone.star file. It is recommended to stay with the same release if possible.
Important:
If you have used a lower node version like 16.13.2, you now must upgrade ALL your doc repos to use v18. See the next steps to do so.
Update Node and npm
- Use
nvm installas described above for a more recent version than the one you have currently installed. - use
npm install npm@latestto update Nodes package manager.
Use a Particular Node Version
Switch to a specific installed version of Node at any time, use the following command:
nvm use 18.20.4Important: If you have additional concurrent terminals open, you must close these terminals first and reopen them to use the new setup.
To make a particular Node version default in new terminals, type:
nvm alias default 18.20.4Install or Update Build Dependencies
Before you can build the documentation, you must install Antora's dependencies. To install them, you just need to run the following command on the command line at the top level of the docs directory. :
npm installThis will install all the dependencies specified in package.json, which is located at the top level of the docs directory.
IMPORTANT: It is recommended that you regularly run npm install as from time to time packages are bumped to newer versions.
With the dependencies installed, you are now ready to build (generate) the ownCloud documentation.
Prepare Your Browser
It is very helpful to see how changes to a page will render without running a build - without including other data images or attributes defined somewhere else, etc. Therefore you can install a plugin for your browser to render .adoc files. You may use the Asciidoctor.js Live Preview or any other that is available for your browser - just search and install a suitable one. Post installing, check that accessing local files in the plugin settings is allowed.
The result shown in the browser may look slightly different to a version that is built via npm run antora-local, but is a good start to get an impression and to catch typos made.
Prepared npm Commands
To see all prepared npm commands, run the following command npm run. This will ouptput all commands with their settings, though this makes readability not easy. See the npm documentation for more information.
Here is the list of commands and when to use them
For Production Environments
The following build commands are used when regular content changes are made or small fixes to the UI are incorporated:
npm run antora
Used when you want to build the documentation where internal links have as basedoc.owncloud.com. The documentation is built for the live environment. Clicking on particular links will then direct to the docs homepage. Use only when you want to check these links or have the CI use them when building.npm run antora-local
This is the command which you will use the most. It is used when you want to build the documentation locally where internal links have as basehttp://localhost:8080. The documentation is fully sourced locally. Ideal for checking withnpm run serveafter content has been updated or added.npm run antora-staging
Used when you want to build the documentation where internal links have as basedoc.staging.owncloud.com. The documentation is built for the staging environment. Note that you manually have to move the content created in/publicto the staging web page to access it. Note that you can also view locally withnpm run servewhich is ideal as first preview step.npm run antora-bundle
Used when you want to build the documentation where internal links have as basedoc.staging.owncloud.com. Compared toantora-staging, this uses a locally builtui-bundle. This build command should be used when you want to test a changed UI before rolling it out.
For Development Environments
The following build commands are used when bigger refactoring, changes or major upgrades including the UI are made:
npm run antora-dev-local
Used when you want to build the documentation where internal links have as basehttp://localhost:8080. Compared toantora-staging, it uses a different site.yml file namedsite-dev.ymlwhich sources manuals not from GitHub but locally.npm run antora-dev-bundle
Used when you want to build the documentation where internal links have as basehttp://localhost:8080. Compared toantora-dev-local, it uses a different site.yml filesite-dev.ymlwhich sources manuals not from GitHub but locally and uses a locally builtui-bundle.
Generating the Documentation
The documentation can be generated in HTML format.
IMPORTANT To build the documentation locally, you must have internet access to get any referenced components or external sources.
Generating HTML Documentation
There are two ways to generate the documentation in HTML format:
- Running Antora from the Command-Line
- Using ownCloud's custom Antora Docker Container
Using Antora from the Command-Line
Using npm, as in the example below, is the easiest way to build the documentation. This project has a predefined target (antora) which calls Antora, supplying all of the required options to build the docs, to build the documentation on any branch of the ownCloud documentation repository.
Note that the build process is essential as it must run error free for a valid documentation. If you push a change with errors, the CI will complain in the Pull request and disallow any merging. For a quick view on the changes made and without having a full build, you can open the changed file in the browser and view it with the installed plug-in which helps finding typos and/or rendering issues quickly.
npm run antora-localUse the following command to view the results in the browser as they will appear on the web.
npm run serveUsing the Docker Container
To build the documentation using the Docker container, from the command line, in the root of the docs directory, run the following command:
docker run -ti --rm \
-v $(pwd):/antora/ \
-w /antora/ \
owncloudci/nodejs:18 \
npm install
docker run -ti --rm \
-v $(pwd):/antora/ \
-w /antora/ \
owncloudci/nodejs:18 \
npm run antoraIf you want to serve your changes locally you have to overwrite the default URL, which points to https://doc.owncloud.com. You can append a custom URL to the command like this:
docker run -ti --rm \
-v $(pwd):/antora/ \
-w /antora/ \
owncloudci/nodejs:18 \
npm run antora --url http://localhost:8080These commands:
- Start up ownCloud's NodeJS Docker container
- Run Antora's
generatecommand, which regenerates the documentation - You can add the
--fetchoption to update the dependent repositories, or any other available flag.
If all goes well, you will not see any console output. If a copy of the container doesn't exist locally, you can pull down a copy, by running docker pull owncloudci/nodejs:18.
Viewing the HTML Documentation
Assuming that there are no errors, the next thing to do is to view the result in your browser. If you have already installed a webserver, you need to make the HTML documentation available pointing to subdirectory public or for easy handling use our predefined npm target so that you can view your changes, before committing and pushing the changes to the remote docs repository. You could also use PHP's built-in webserver as well.
The following example uses our npm target, to start it run the following command in the root of your docs repository:
npm run serveThis starts a simple webserver, using the public directory, (re)generated by antora, as the document root, listening on http://localhost:8080. Open the URL in your browser of choice and you'll see two links, as below.
NOTE: You will likely get a screen with the message "Page not found". In this case, you have to select the manual to view on the left side of the browser window. For ownCloud Classic, select master as you usually start working there.
If you're happy with your changes, create a set of meaningful commits and push them to the remote repository. If you're not satisfied, continue to work on the file(s) and start the build process again. Your changes will be reflected in the local version of the site that Serve is rendering.
We hope that you can see that contributing to the documentation using Antora is a pretty straight-forward process, and not that demanding.
Viewing Build Errors
If an aspect of your change contains invalid AsciiDoc, then you'll see output similar to the example below.
asciidoctor: ERROR: index.adoc: line 25: only book doctypes can contain level 0 sectionsThere, you can see:
- That an error was found
- The file it was found in
- The line of that file where it is located
Setting up an Antora Development Environment
Setting up an Antora development environment can be necessary when doing tasks outside of classical content addition or updating. It is essential when starting a refactoring, UI changes or implementing new functionalities.
Note that all doc repositories must be local on the same filesystem level. Use any path that fits your needs like:
/dev/docs
/dev/docs-ocis
/dev/docs-client-desktop
...There are some important steps when starting such a task. The following steps have to be done for the doc repo you are testing. Note that only the site.yml file of the respective repo is used for building the respective component. Other site.yml files are not used in the build process, though they may exist for testing purposes.
Make a branch in the respective doc repos where you will do the changes necessary and check the output.
Do not create pull requests before you are sure a build returns the correct results.If there are more repos affected by the changes intended, you need to select the one repo for building, that includes all repos (components) that will be changed. That repo is the source for the next step.
Run
bin/prepare_site_ymlin the repo you are developing on or the one that includes all required repos to get asite-dev.yml.
This file will not get published and will always stay local. It is a mirror of the currentsite.ymlbut the URLs formerly pointing to GitHub and the respective repos will get changed to fetch the components locally.Before you start changing, run
npm installto have the dependencies updated.Depending on what you are developing on, either run:
npm run antora-dev-localornpm run antora-dev-bundlefrom the repo you want to build from which will use the formerly createdsite-dev.yml.Finally, run
npm run serveto see the result of the build.If the changes are fine, create a PR from the respective branches and continue as usual.
If the changes need to be dropped, run
npm installfrom the master branch in the repos with changes again to revert any dependencies that may have changed.
Note that you may need changes and testing in more than one component like docs or docs-ocis to get a correct final result.
IMPORTANT
Though components get sourced locally when running npm run antora-dev-xxx, some content will still get pulled from external sources when defined in a page. This means that, for development, you still must have an internet connection, like when doing normal builds. If an internet connection is not present, errors will be thrown and the build stops.
Using Search in Production or Development
The search bar is the component on the top right of the documentation where one can enter a term and get matches. If something is found, the matches are displayed as suggestions that can be clicked.
Search is powered by Pagefind, a static search library. There is no server, container, or secret to set up: Pagefind crawls the already-built HTML in public/ and writes a static, chunked index into public/pagefind/. Because it runs over the build output, the index automatically covers every component and version included in that build.
Follow this procedure to build and use search locally:
Build the site as usual with any
npm run antora-xxxcommand, for example:textnpm run antora-localIndex the built site. This reads
public/and writespublic/pagefind/:textnpm run pagefindThe command prints a short summary of how many pages and words were indexed.
Serve the build and open it in the browser:
textnpm run serveEnter any search term into the search field to see matches returned.
In CI, the production build runs npm run antora followed by npm run pagefind before deploying public/, so the deployed site always ships a fresh index. Re-run npm run pagefind whenever the HTML changes; serving a build without indexing it first yields an empty search.
Resolving Edit-this-page in Development
When doing a local build, the link Edit this page on the top right resolves to the local file system. If you want to make Antora to resolve to where the files are sourced on github, you need to build using the envvar CI=true. This can be done with the following command:
CI=true \
npm run antora-localPackage and Dependency Management
Packages and dependencies are managed by the setup automatically.
In case it is necessary to add or remove packages, you need to do this in the package.json file. Add new packages issuing npm add . Then you delete the package-lock.json file and run npm install. All dependencies are resolved automatically and a new lock file is created. You then need to push both changed files and create a PR.
IMPORTANT: This procedure is also true when "backporting" a change of the package file to the target branch. A normal backport process will break the lockfile and you will get errors reported from the CI.
TIPS
Additional Command Line Parameters
You can add additional parameters to the currently defined ones or overwrite existing ones, for example, defining the default URL or additional global attributes. Just add them to the npm run antora command.
Searching and Fixing Attribute Errors
It is very beneficial to use command-line attributes when searching and fixing attribute errors. This can be necessary when you get warnings like: WARNING: skipping reference to missing attribute: <attribute-name>.
- First, you may want to check if the attribute name is used as an attribute at all. Run at the top level of the docs repo:
grep -rn --exclude-dir={public,.git,node_modules} \{attribute-name}
If found, check if the attribute definition is made or passed or needs exclusion. - If no result is found, it may be the case that the error-causing attribute is not in the master
branch but in another one. This can be identified by adding a custom attribute to thenpm run antoracommand like:--attribute the-erroring-attribute=HUGOwhere HUGO can be anything that is not used and easy to grep. - Finally, run in the
publicdirectory:grep -rn HUGO. You will see exactly in which branch and file the issue occurs.
If it is a branch other thanmasterand an ongoing but not merged fix that targets this issue, you have to
merge the changes first, and then backport them to the branch. Do not forget to sync the branch post merging too.
Having done that, re-runningnpm run antorashould eliminate that particular missing attribute warning.
Fixing a Directory Not Found Error
If you get an error like: Error: ENOENT: no such file or directory, lstat '/var/owncloud/docs/cache/, you just need to delete the cache directory with the command below (use the error path printed) and restart the build process.
rm -r /var/owncloud/docs/cacheManually Restarting CI
In case CI needs to be restarted, which can happen in the rare case it was not triggered post pushing automatically, you need to manually (re)start the CI. This can be done by either triggering drone from the CLI if you have access or by creating an empty commit and pushing it. To do so, change to the branch in question and follow the git commands below:
git commit --allow-empty -m "restart ci"
git pushFile: docs/checking-broken-links.md
Checking Broken Links
Introduction
Checking for broken links is a science on its own. External webpages, internal sites and
references to anchors can cause broken links in various ways. While it looks relatively
easy to check for broken anchors, not many free tools provide this functionality.
Various tools behave and report access to links in different ways. Configuration, like the
possibility to define patterns in an elegant way to exclude link searches, is also a rare feature.
There is no free one-fits-all tool which means you may have to use more than one tool to
differentiate real broken links from false positives or to get results the other tools may not provide.
Preparation
To check broken links, you need to prepare with the following steps:
- Make the compiled documentation available for browsing by using a webserver like
our npm target, PHP's built-in webserver, Apache or NGINX - Build the local docs with
npm antora --url http://localhost:8080 - Install a Broken Link Checker of your choice (see the examples below)
Use the broken link checker of your choice, the following are usable examples. The command examples assume that the documentation built is accessible via http://localhost:8080.
Note You may get false positives because of sample links or addresses pointing to nowhere. This is normal and not a broken link.
Note It is good to pipe the output of the results to a file for easy checking.
Link Checkers provided by the Documentation
Antora xref-validator
The Antora xref-validator provided by the Antora core team, is able to check the native Antora xref links. It is automatically installed when you run npm install for the Antora setup in the root of your local clone of the docs repository. It doesn't check external links, but it's still a good start.
Using npm Validate
This is the easiest way and uses the xref-validator to validate the documentation, using predefined settings.
npm validateUsing the Validator with Own Settings
If you want to use your own settings, run the command passing the necessary parameters manually, as in the example below.
antora generate \
--generator=./generators/xref-validator.js \
site.ymlExample Output
If invalid xrefs are detected, it will output them to the console, You can see that it checks all the content source repositories and lists the file that contains the broken xref:
worktree: /var/www/owncloud/docs | component: server | version: master
path: modules/admin_manual/nav.adoc | xref: configuration/server/security/password-policy.adoc
path: modules/admin_manual/pages/configuration/files/external_storage/configuration.adoc | xref: server/import_ssl_cert.adoc
path: modules/admin_manual/pages/configuration/files/file_sharing_configuration.adoc | xref: server/configuration/server/security/password_policy.adocPublicly Available Linkcheckers
htmltest by Will Pimblett
This is an extremely fast and very comfortable / configurable link checker written in go.
A description of htmltest can be found here.
Follow this procedure, to install dart and
this link to install htmltest.
A System-wide Install is recommended.
To check docs, you first need to build the actual docs running npm antora-local. This creates all necessary files in the public directory.
Then run htmltest -s public in the root of docs/ to check the build. Note that it is not mandatory to have a webserver running like npm serve. The -s option skips external link checks which speeds up time a lot and reduces the output. To include external links, omit the -s option. If you are running the check from another repo than docs you may want to add | grep -v '\|manifest.json\|apple-touch-icon.png\|favicon.svg\|favicon-32x32.png\|favicon-16x16.png\|safari-pinned-tab.svg' to omit any output regarding missing favicons as they are only added in the full docs build but not in local builds.
Note that htmltest checks the complete public/ directory including all products and all branches built. Due to this fact, you possibly get the same entries for each product/branch affected. As a rule of thumb, first look for next or latest branch entries like 10.x, fix the issue, backport it if necessary and restart the procedure.
Note, to reduce false positives like 503 which are being reported by https://www.php.net/ links, filter the results for 404. Some, but only a few 404 results are false positives like Google Playstore links, the URL can be accessed on the browser without any issues.
Note, run htmltest public which includes checking external links from the master branch to avoid antora build artifacts linking to the branch name.
Example Output
server/10.8/admin_manual/maintenance/export_import_instance_data.html
hash does not exist --- server/10.8/admin_manual/maintenance/export_import_instance_data.html --> #what_is_exported
hash does not exist --- server/10.8/admin_manual/maintenance/export_import_instance_data.html --> #known_limitations
hash does not exist --- server/10.8/admin_manual/maintenance/export_import_instance_data.html --> ../configuration/server/occ_command.html#data_exporter
hash does not exist --- server/10.8/admin_manual/maintenance/export_import_instance_data.html --> #known_limitationsAs you can see in the example above, the file admin_manual/maintenance/export_import_instance_data.html has broken anchors. To fix the links, open admin_manual/pages/maintenance/export_import_instance_data.adoc (the pages directory has to be included in the path, .html replaced by .adoc), search for the item reported (e.g. #what_is_exported and correct it. When searching, replace any references to doc internal pages from .html to .adoc like configuration/server/occ_command.html#data_exporter --> configuration/server/occ_command.adoc#data_exporter
Linkcheck by Filip Hracek
This is an extremely fast and very comfortable / configurable link checker written in go.
A description of linkcheck can be found here.
Follow this procedure,
to install or update linkcheck, which needs dart:
To run it, you must have one terminal open and run npm serve to start a http server and in another terminal the linkcheck command:
Because linkcheck provides the possibility to use a file to exclude search patterns,
it is good advice to create a file with the following predefined content. In this example,
the file is named my_skip_file.txt and saved one level below the local docs repository.
Adapt the content to your needs.
# exclude check to particular sub-pages of owncloud.com
https://owncloud.com/news
https://owncloud.com/support
https://owncloud.com/install
# because of denied by robots.txt
https://github.com
https://gist.github.com
https://www.samba.org
https://linux.die.net
https://mycloud.org
https://www.google.de
https://www.tscp.org
# known false positives
https://www.cyberciti.biz/faq/upgrade-ubuntu-18-04-to-20-04-lts-using-command-line/
https://www.technetexperts.com/mobile/creating-static-library-in-ios-app-development/
# no missing favicons when localhost
http://localhost:8080/manifest.json
http://localhost:8080/apple-touch-icon.png
http://localhost:8080/favicon.svg
http://localhost:8080/favicon-32x32.png
http://localhost:8080/favicon-16x16.png
http://localhost:8080/safari-pinned-tab.svg
# example links like: https://<your-owncloud-server>/ or https://{{.preferred_username}}
# or image generation (kroki)
https://%3C
https://%7B%7B
https://www.example.com
https://kroki.ioIt is good practice to first start checking excluding external pages / sites.linkcheck will report internal broken links AND broken links to anchors.
Note: you can pipe the result into a file. Just add in > ../linkcheck.log.
The grep filter reduces the output to important ones.
linkcheck --skip-file ../my_skip_file.txt --no-connection-failures-as-warnings | grep "HTTP 40"Fix any broken internal links found reported.
Continue with checking also external pages / sites:
linkcheck -e --skip-file ../my_skip_file.txt --no-connection-failures-as-warnings | grep "HTTP 40"Example Output
No URL given, checking http://localhost:8080/
Crawling...
http://localhost:8080/server/admin_manual/appliance/wnd_setup.html
- (1297:3) 'Windows ..' => http://localhost:8080/server/admin_manual/enterprise/external_storage/windows-network-drive_configuration.html#wnd-listen (HTTP 200 but missing anchor)
...
http://localhost:8080/server/admin_manual/configuration/database/linux_database_configuration.html
- (1451:3) 'https://..' => https://mariadb.com/kb/en/mariadb/xtradbinnodb-server-system-variables/%5C#innodb_large_prefix (connection failed)
- (1457:3) 'http://m..' => http://mechanics.flite.com/blog/2014/07/29/using-innodb-large-prefix-to-avoid-error-1071/ (connection failed)In the example output above, the first entry HTTP 200 but missing anchor highlights a broken link to an anchor.
The second entry connection failed highlights the possibility that the page may no longer be accessible.
You have to manually check if it is a false-positive or not.
File: docs/doc-guidelines.md
Documentation Guidelines
The focus of our documentation is to help users install, configure, run, enjoy, and upgrade ownCloud products, even troubleshoot if necessary. The target audience ranges from curious tech aficionados to experienced system administrators and beyond. Provide all relevant information, and do not assume a certain skill level or minimum knowledge.
It is important to know that proper documentation also helps developers in all stages of the development process and is early proof of how a potential user will see or interpret the outcome. The key to professional documentation is communication, testing, and proofreading. To achieve this, we've developed the following process, which naturally gets adjusted as we learn better ways to handle things.
Our documentation is hosted on GitHub in various repositories targeting different audiences. In the following description, we assume familiarity with GitHub and git commands. Text is written in AsciiDoc and generated via Antora. For further information on how to format your text, check out: https://asciidoctor.org/docs/asciidoc-recommended-practices/.
If you're new to writing or editing ownCloud documentation, we recommend the Getting Started Guide and Building the Documentation to get a good understanding of what awaits you. (Just don't let it discourage you!). Keep the Best Practices Guide collection in mind.
To contribute to the documentation by providing content or fixing issues in the existing documentation:
- Clone the respective repository.
- Create a local branch.
- Edit an existing file or add a new one.
Before pushing the file to Github, please take care of the following:
- Our documentation language is American English. If in doubt how things are written, consult a dictionary or use a spell-checker. If in doubt about your English language skills in general, request a language review from
@mmattelor@phil-daviswhen you create a pull request on Github. - While writing or editing, please follow the Style Guide.
- Build the documentation and check the layout.
Commit all changed files and push the branch to GitHub.
Now, log in to Github and find the branch you pushed, create a pull request and follow the rules below to make the process quick and easy for everyone:
4 Eyes Principle (4EP)
Each pull request (PR) on Github must pass the 4EP. This means that each PR needs approval before merging into the master branch. Add technical reviewers for peer reviews or anyone else who can give you valuable feedback. The author and reviewers share the responsibility of driving the process forward. A reviewer should merge after approval if no more steps or reviews are needed. Otherwise, the reviewer should point out any next steps needed (e.g., backports), ask for more reviews or ask the author to take action (e.g., please merge after extra reviews or steps). Particularly if you don't want to take care of everything else in the approval and merge process, like backports, add one the following persons as reviewers:
@mmattel,@phil-davis.Exceptions to the 4EP must be documented in the PR description and can be made if:
- Language violations require immediate action,
- The docs web site is not usable, partially or in full, without an emergency docs PR.
Security and Dependency Bumps
These PRs are usually made by the bot but can also be created manually. SDB are related to the build process tools. The 4EP applies. The approver must take responsibility not to break the existing setup. Mandatory: add
@mmattelor@phil-davisas reviewer.The main branch for changes is
master
Any changes start there. Exception:
Changes only apply to the branch the PR is made for, mandatory add a comment note.Technical and Process Changes
Technical and process changes are changes like prerequisites, installation, upgrades, API etc. They must first be tested by the author of the change, step by step, before documenting them.
The PR title should summarize what the changes are about
Provide in the PR description the following information
This gives reviewers a quick but thorough understanding of what they should be looking for.- What changes or additions you made
- The positive impact of these changes if they aren't glaringly obvious
- Special notes like the wish for language proofing
- To which branches the PR needs to get backported (usually to the current release and the previous one for corrections to existing documentation)
- A link to the docs issue if one exists
- A link to the issue/PR in the corresponding repo this change will fix.
Backporting
If backports are necessary, either use the documented backporting script which you can find in the
bin/directory of the docs repo or do it manually and give the backport the following headline:[target branch] [source PR number] original headline
Example:[10.15] [3456] Fix missing php libraryAs comment use
Backport of #3456where 3456 is the source PR number.
This links the backport to the source PR. Set the labelbackport.The 4EP applies.
Predefined Global Attributes
Attributes are like variables and will be replaced by the build process. Predefined global attributes are defined in either site.yml, the global-attributes.yml file in the docs repo and/or antora.yml which is located in the top level directory of your repository and affect all pages where this attribute is used. If an attribute exists for a case, use it. Read the Best Practises Guide in the docs repo for more information on how to do that.
- Support Community Contributors
If one of the items listed above is missing in a contribution of a community member, add the relevant missing information. Leave a note of appreciation for the contributor and help with finalizing the PR.
File: docs/extensions.md
Extensions
The documentation uses extensions that are added via the site.yml file. Some extensions are mandatory for the build process, some of them are optional. There is an own repository that provides details to each extension used plus lists extensions which are currently not used but are candidates. See the Useful Antora and Asciidoc Extensions repository for more details.
Mandatory Extensions
Asciidoc
- Add Tab Sets:
./ext-asciidoc/tabs.js - Include Content via URL:
./ext-asciidoc/remote-include-processor.js - Convert diagrams to images:
asciidoctor-kroki # integrated via npm
Antora
- Load Global Site Attributes:
./ext-antora/load-global-site-attributes.js
Optional Extensions
Antora
- Print Component Version File Table:
./ext-antora/comp-version.js - Print Attributes Used in Playbook:
./ext-antora/attributes-used-in-site-yml.js - Print Attributes Used in Component Descriptor:
./ext-antora/attributes-used-in-antora-yml.js
UI
Though not an Antora/Asciidoc extension, but required for presenting images:
docs-ui
- Medium-Zoom
File: docs/getting-started.md
Getting Started
This guide is here to help you get started with this repository, primarily if you've been contributing to the previous version of ownCloud's documentation, which used reStructuredText and Sphinx-Doc.
For Non-Developers
Even if you’re not a developer, you can contribute to the ownCloud documentation by creating new issues and contributing to the discussion around them. You don’t need to be familiar with how to write or edit code, nor install any software. All that you need is a web browser, such as Google Chrome, Mozilla Firefox, Apple Safari, or Microsoft Edge.
NOTE: Most browsers support live preview.
Initial Steps
Before you can contribute to the documentation, you need to:
Have a GitHub Account
If you don't already have an account, you can sign up for a new one. You only need to provide a username, email address, and a password.
Know the AsciiDoc Basics
While the AsciiDoc file format is quite rich, you're likely to only need a small portion of it, a lot of the time. In the example below, you can see a small example which shows how to format headers, paragraphs, links, lists, and source code.
= Top-Level Header
An introduction to http://asciidoc.org[AsciiDoc].
== Second-Level Header
* item 1
* item 2
[source,ruby]
====
puts "Hello, World!"
====Have a read through the AsciiDoctor Syntax Quick Reference to familiarise yourself with the format's essentials. Please also refer to Best Practices and Tips for more information.
Creating New Issues
Creating new issues is one of the most helpful ways to contribute to the ownCloud documentation. Issues document changes that need to be made because:
- Information is missing, incorrect, or outdated; or
- A new feature has been created that needs to be documented.
To create a new issue, open https://github.com/owncloud/docs/issues in your browser and click "New Issue" on the far right-hand side of the page. This takes you to the New Issue form.
First, enter a concise title, that describes the change that needs to be made. Please make it only as long as it needs to be, the shorter, the better.
Next, enter a description that describes the required change in greater depth. The description field is pre-loaded with a template which is designed to help you fill out a meaningful description.
Four sections should be filled out (the more, the better):
- What type of content change is this?
- Which Manual Does This Relate to?
- What Needs to be Documented?
- Why Should This Change Be Made?
Each section has a comment, the text inside ``, designed to guide you about what you need to cover. The comment text is not visible when viewing the issue.
Note: The description text can be, if desired, formatted with Markdown, which is a simple way of formatting text, to give it more significant meaning.
After you've filled out a title and description, optionally assign the issue to the most relevant people, by clicking the cog icon, on the right-hand side of the Assignee field, and selecting one or more users from the list that appears. You can also add one or more labels, to categorise the new issue, if you so choose.
Assigning an issue helps ensure that the issue can be acted on as soon as possible. If you're not sure whom to assign it to, please do not assign it to anyone.
Once you've completed these steps, at the bottom of the form, click the "Submit new issue" button, which creates the new issue, and optionally assigns it to the nominated people.
Now that the issue is created, the relevant developer(s) and other stakeholders can discuss the request, asking for clarification and further information if required, and can work through the request until it's completed. You will also see it in the issues list, which you can see an example of in the screenshot below.
For Developers
Initial Steps
To contribute to the documentation, you need to:
- Learn Antora's basics.
- Learn the AsciiDoc basics.
In addition, check out the Asciidoctor Writers Guide, User Manual, and Syntax Quick Reference. - Make sure you have tools that can edit and preview AsciiDoc files.
- Setup a GitHub account, if you haven't already.
- Setup your local copy of the docs repository
- Environmental setups depending on the kind of changes
- Contributing to the documentation
- Getting support
Setup Your Local Copy of the Docs Repository
With this done, you then need to get your local copy of the docs repository ready. To do this, follow these three steps.
Fork the docs repository.
This is necessary, as you won't be able to push changes directly to the docs repository.Clone the docs repository locally and enter it.
consolegit clone [email protected]:owncloud/docs.git cd docsAdd a remote to your fork, by substituting your GitHub username in the command below.
consolegit remote add {username} [email protected]:{username}/docs.git git fetch {username}
Environmental Setups Depending on the Kind of Changes
Depending on if you are making text changes only or if you change images, inline code examples or more complex content, you may need to use different tools to validate your outcome.
You Are Making Text Changes Only
If you're making text changes only, we recommend installing the AsciiDoc Live Preview plugin(s):
- To your browser:
- Firefox: asciidoctorjs-live preview
- Other browser (The supported browsers are: FireFox, Google Chrome, or Opera, -- if FireFox installation fails, try the above instead).
- To your text editor or IDE, if it has one.
Using one, or both, of these, you can quickly check if the changes you make are what you expect, and if there are any render errors. If the document renders as expected, then you can commit the changes and push them to the docs repository.
NOTE: Any links to internal files, such as code samples, and images will not render correctly, as the paths do not contain the absolute path to the asset. Links to internal files can only be previewed when the documentation is generated with Antora.
You Are Working With Inline Code Examples, Images, and Attachments
If, however, you're linking to local files, such as inline code examples, images, and attachments, then you need to install Antora's command-line tools. This is because the Live Preview plugin won't know the complete path to the local file, so won't be able to correctly render a link to it. All other kinds of links should work properly, however.
In this case, you need to use Antora to regenerate the documentation and manually check if there are any broken links or if something looks amiss.
Next, you need to learn how to build the docs from the command line and how to review the changes in your browser.
Broken Link Checker
To check for broken links manually, see install and use a broken link checker.
Contributing to the Documentation
With that done, you're now ready to make regular contributions to the docs. To do that, here are the steps to follow to contribute changes.
- Create a local development branch off of
masteror another development branch and switch to it.
You can do this in one command:git checkout -b {branch-name}.
We recommend naming the branch such that you'll recognize its purpose; e.g.,deprecate-some-occ-command,document-firebase-database-support. - Do some work, commit, repeat as necessary.
- Push the branch to your remote fork of the docs repository.
- Send a pull request from your fork to the docs repository.
Here's an example of contributing to the documentation
$ git checkout -b deprecate-some-occ-command
Switched to a new branch 'deprecate-some-occ-command'
... do some work ...
$ git commit
... write your log message ...
$ git push {username} deprecate-some-occ-command:deprecate-some-occ-command
Counting objects: 38, done.
Delta compression using up to 2 threads.
Compression objects: 100% (18/18), done.
Writing objects: 100% (20/20), 8.19KiB, done.
Total 20 (delta 12), reused 0 (delta 0)
To ssh://[email protected]/{username}/docs.git
b5583aa..4f51698 HEAD -> masterCleaning Up Your Branches After They're Merged
If you are a frequent contributor, you'll likely create many branches, both locally and remotely. To avoid confusing which ones are new and which are old, once your pull requests are merged into the master repository, we suggest removing the underlying branches. Here's how to do this.
Local Branch Cleanup
$ git branch -dRemote Branch Removal
$ git push {username} :Note: you can also delete a remote branch through the GitHub UI.
The Branching Workflow
The branching workflow is only necessary for versioned repos (documentations). Please refer to the branching workflow to learn about how git branches are used to manage and build the documentation.
Backporting
If you want or need to backport a merged PR, you can easily do that by using the linked backport script. In the repo where the backport is needed, update the branch containing the merged PR and copy the merge commit. Run the command using the merge commit ID with the target branch where the backport needs to be applied to. All individual commits of the merge will be backported.
Note that it may occur that you have conflicts, resolve them first with standard git methods to proceed.
The script requires the xdg-utils package which opens the PR to be finalized in your browser. macOS does not need this package. Replace the command xdg-open with open at the end of the script.
If you want to make this script part of the git command set, create a git alias:
Open the ~/.gitconfig file with the editor of your choice and add the following:
[alias]
backport = !bash -c '/backport.sh $1 $2' -You can now create a backport by invoking the following command:
git backport <merge ID> <target branch>Build Pipeline and Web Deployment
Please refer to the documentation build pipeline to learn about how the documentation is built and deployed to production.
File: docs/html-to-pdf.md
HTML to PDF
The script bin/ownCloudDocPdf.py, temporarily necessary until Antora is upgraded to version 3, allows users to convert a sequence of web pages to the PDF format. It navigates through pages of a manual by following a "next" link on each page and converts each page to a PDF. The PDFs are then merged into a single PDF file for further use. Note that this script has a chance to miss pages as it is based on continuous chains of "next" links compared to Antora generated pdf which accesses a full content catalogue.
How to Use
The script requires Python to be installed and some libraries provided by the OS and is executed from the command line. It accepts a URL as an argument.
python bin/ownCloudDocPdf.py [URL]Example
python bin/ownCloudDocPdf.py https://doc.owncloud.com/webui/next/classic_ui/Dependencies
Python (Script developed and tested with version 3.10)wkhtmltopdfpdftkrequests
Installing Dependencies
Install the Python requests library:
python -m pip install requestsOn Debian-based systems, install wkhtmltopdf and pdftk using:
sudo apt-get install wkhtmltopdf pdftkOn other systems, please refer to the documentation for wkhtmltopdf and pdftk for installation instructions.
Output
The script will output a PDF file named output.pdf in the current directory. If a file with that name already exists, the script will increment a number in parentheses until it finds an unused filename (like output(1).pdf, output(2).pdf, etc.).
Notes
The temporary PDF files generated for each page are stored under /tmp/ and are deleted after the final PDF is merged.
Ensure that you have write permissions in the directory where the script is run, as it will attempt to save the output PDF in that location.
File: docs/install-antora.md
Install Antora
Installing Antora on your local development (virtual) machine doesn't take too much time, based on whether you install the tools directly.
Please note: if you just want to make text changes, then installing the AsciiDoc Live Preview Plugin, whether as a Browser plugin, or as part of your text editor or IDE, may be sufficient for your needs.
Install The Antora Tools Locally
To install all the Antora tools on your local machine will take a bit of time and effort. Before you get started, make sure that your development machine is one of the supported platforms. Note, if possible, aviod using Windows as it more and more conflicts with extensions and tools.
Though your system may have installed yarn, package management and issuing the build must not use yarn but npm which is part of the node installation.
With the dependencies and Antora tools installed, you’re ready to build the documentation locally.