├── .asciidoctorconfig ├── .drone.star ├── .github ├── dependabot.yml ├── issue_template.md └── settings.yml ├── .gitignore ├── .prettierrc ├── LICENSE ├── README.md ├── bin ├── git_commands │ ├── backport.sh │ ├── getcommits.sh │ ├── getpull.sh │ └── squash.sh ├── manual_config_pdf ├── optimize_crawl ├── ownCloudDocPdf.py └── prepare_site_yml ├── book_templates ├── ownCloud_Admin_Manual.adoc ├── ownCloud_Developer_Manual.adoc └── ownCloud_User_Manual.adoc ├── docs ├── antora-site-structure.md ├── best-practices.md ├── build-the-docs.md ├── checking-broken-links.md ├── doc-guidelines.md ├── extensions.md ├── getting-started.md ├── html-to-pdf.md ├── images │ ├── antora-ui-anotated.png │ ├── antora-version-navigation.png │ ├── asciidoc-syntax-quick-reference.png │ ├── editing-asciidoc-in-atom.png │ ├── editing-asciidoc-in-phpstorm.png │ ├── editing-asciidoc-in-sublime-text.png │ ├── editing-asciidoc-in-vim.png │ ├── editing-asciidoc-in-vscode.png │ ├── getting-started │ │ └── non-developers │ │ │ ├── add-comment-to-issue.png │ │ │ ├── assign-issue.png │ │ │ ├── commit-change-to-docs-directly-on-github.png │ │ │ ├── create-new-issue.png │ │ │ ├── current-docs-issues.png │ │ │ ├── docs-home-edit-this-page.png │ │ │ ├── docs-repo-home.png │ │ │ ├── edit-page-on-github-directly.png │ │ │ ├── github-signup.png │ │ │ └── new-docs-issue.png │ ├── the-branching-workflow.key │ ├── the-branching-workflow.png │ ├── viewing-asciidoc-in-firefox-with-the-asciidoc-live-preview-plugin.png │ ├── viewing-the-locally-generated-antora-documentation.png │ ├── what-is-antora │ │ └── the-antora-version-changer.gif │ └── what-is-asciidoc │ │ ├── setting-imagesdir-in-atom.png │ │ └── setting-imagesdir-in-intellij.png ├── install-antora.md ├── new-version-branch.md ├── style-guide.md ├── test-ui-bundle.md ├── the-branching-workflow.md ├── the-build-pipeline.md ├── what-is-antora.md └── what-is-asciidoc.md ├── es-docker-compose.yml ├── ext-antora ├── attributes-used-in-antora-yml.js ├── attributes-used-in-site-yml.js ├── comp-version.js ├── generate-index.js └── load-global-site-attributes.js ├── ext-asciidoc ├── remote-include-processor.js └── tabs.js ├── fonts ├── dejavu-sans-bold.ttf ├── dejavu-sans-boldoblique.ttf ├── dejavu-sans-condensed.ttf ├── dejavu-sans-condensedbold.ttf ├── dejavu-sans-condensedboldoblique.ttf ├── dejavu-sans-condensedoblique.ttf ├── dejavu-sans-extralight.ttf ├── dejavu-sans-mono-bold.ttf ├── dejavu-sans-mono.ttf ├── dejavu-sans-monoboldoblique.ttf ├── dejavu-sans-monooblique.ttf ├── dejavu-sans-oblique.ttf ├── dejavu-sans.ttf ├── dejavuserif-bold.ttf ├── dejavuserif-bolditalic.ttf ├── dejavuserif-italic.ttf ├── dejavuserif.ttf ├── dejavuserifcondensed-bold.ttf ├── dejavuserifcondensed-bolditalic.ttf ├── dejavuserifcondensed-italic.ttf ├── dejavuserifcondensed.ttf ├── mplus-1mn-bold.ttf ├── mplus-1mn-medium.ttf ├── mplus-1mn-regular.ttf ├── mplus-1mn-thin.ttf ├── mplus-1p-regular.ttf ├── notoserif-bold.ttf ├── notoserif-bold_italic.ttf ├── notoserif-italic.ttf ├── notoserif-regular.ttf ├── opensans-bold.ttf ├── opensans-bolditalic.ttf ├── opensans-extrabold.ttf ├── opensans-extrabolditalic.ttf ├── opensans-italic.ttf ├── opensans-light.ttf ├── opensans-lightitalic.ttf ├── opensans-regular.ttf ├── opensans-semibold.ttf └── opensans-semibolditalic.ttf ├── global-attributes.yml ├── overlay ├── android-chrome-192x192.png ├── android-chrome-512x512.png ├── apple-touch-icon-120x120.png ├── apple-touch-icon-152x152.png ├── apple-touch-icon-180x180.png ├── apple-touch-icon-60x60.png ├── apple-touch-icon-76x76.png ├── apple-touch-icon-precomposed.png ├── apple-touch-icon.png ├── browserconfig.xml ├── favicon-16x16.png ├── favicon-32x32.png ├── favicon.ico ├── favicon.svg ├── favicon.txt ├── manifest.json ├── mstile-144x144.png ├── mstile-150x150.png ├── mstile-310x150.png ├── mstile-310x310.png ├── mstile-70x70.png ├── opengraph-android.png ├── opengraph-branding.png ├── opengraph-default.png ├── opengraph-desktop.png ├── opengraph-docs.png ├── opengraph-ios-app.png ├── opengraph-ocis.png ├── opengraph-server.png ├── opengraph-user.png ├── opengraph-webui.png ├── robots.txt ├── safari-pinned-tab.svg └── ui.yml ├── package-lock.json ├── package.json ├── pdf_web └── .gitignore ├── resources └── themes │ ├── custom-theme.yml │ └── owncloud-theme.yml └── site.yml /.asciidoctorconfig: -------------------------------------------------------------------------------- 1 | // IntelliJ AsciiDoc/Antora Plugin 2 | :linkcss: 3 | :stylesdir: https://doc.owncloud.com/assets/css/ 4 | :stylesheet: site.css -------------------------------------------------------------------------------- /.drone.star: -------------------------------------------------------------------------------- 1 | # Environment variables needed to generate the search index are only provided here in the docs repo in .drone.star 2 | # Also see the documentation for more details. 3 | 4 | def main(ctx): 5 | # Config 6 | 7 | # There is only one branch to be deployed 8 | deployment_branch = "master" 9 | 10 | return [ 11 | checkStarlark(), 12 | build(ctx, deployment_branch), 13 | ] 14 | 15 | def checkStarlark(): 16 | return { 17 | "kind": "pipeline", 18 | "type": "docker", 19 | "name": "check-starlark", 20 | "steps": [ 21 | { 22 | "name": "format-check-starlark", 23 | "image": "owncloudci/bazel-buildifier", 24 | "pull": "always", 25 | "commands": [ 26 | "buildifier --mode=check .drone.star", 27 | ], 28 | }, 29 | { 30 | "name": "show-diff", 31 | "image": "owncloudci/bazel-buildifier", 32 | "pull": "always", 33 | "commands": [ 34 | "buildifier --mode=fix .drone.star", 35 | "git diff", 36 | ], 37 | "when": { 38 | "status": [ 39 | "failure", 40 | ], 41 | }, 42 | }, 43 | ], 44 | "depends_on": [], 45 | "trigger": { 46 | "ref": [ 47 | "refs/pull/**", 48 | ], 49 | }, 50 | } 51 | 52 | def build(ctx, deployment_branch): 53 | return { 54 | "kind": "pipeline", 55 | "type": "docker", 56 | "name": "documentation", 57 | "platform": { 58 | "os": "linux", 59 | "arch": "amd64", 60 | }, 61 | "steps": [ 62 | { 63 | "name": "cache-restore", 64 | "pull": "always", 65 | "image": "plugins/s3-cache:1", 66 | "settings": { 67 | "endpoint": from_secret("cache_s3_server"), 68 | "access_key": from_secret("cache_s3_access_key"), 69 | "secret_key": from_secret("cache_s3_secret_key"), 70 | "restore": "true", 71 | }, 72 | }, 73 | { 74 | "name": "docs-deps", 75 | "pull": "always", 76 | "image": "owncloudci/nodejs:18", 77 | "commands": [ 78 | "npm install", 79 | ], 80 | }, 81 | { 82 | "name": "docs-build", 83 | "pull": "always", 84 | "image": "owncloudci/nodejs:18", 85 | "environment": { 86 | "UPDATE_SEARCH_INDEX": ctx.build.branch == deployment_branch, 87 | "ELASTICSEARCH_NODE": from_secret("elasticsearch_node"), 88 | "ELASTICSEARCH_INDEX": from_secret("elasticsearch_index"), 89 | "ELASTICSEARCH_READ_AUTH": from_secret("elasticsearch_read_auth"), 90 | "ELASTICSEARCH_WRITE_AUTH": from_secret("elasticsearch_write_auth"), 91 | }, 92 | "commands": [ 93 | # runs the antora script including config defined in package.json 94 | "npm run antora", 95 | "bin/optimize_crawl -x", 96 | ], 97 | }, 98 | { 99 | "name": "cache-rebuild", 100 | "pull": "always", 101 | "image": "plugins/s3-cache:1", 102 | "settings": { 103 | "endpoint": from_secret("cache_s3_server"), 104 | "access_key": from_secret("cache_s3_access_key"), 105 | "secret_key": from_secret("cache_s3_secret_key"), 106 | "rebuild": "true", 107 | "mount": [ 108 | "node_modules", 109 | ], 110 | }, 111 | "when": { 112 | "event": [ 113 | "push", 114 | "cron", 115 | ], 116 | }, 117 | }, 118 | { 119 | "name": "cache-flush", 120 | "pull": "always", 121 | "image": "plugins/s3-cache:1", 122 | "settings": { 123 | "endpoint": from_secret("cache_s3_server"), 124 | "access_key": from_secret("cache_s3_access_key"), 125 | "secret_key": from_secret("cache_s3_secret_key"), 126 | "flush": "true", 127 | "flush_age": "14", 128 | }, 129 | "when": { 130 | "event": [ 131 | "push", 132 | "cron", 133 | ], 134 | }, 135 | }, 136 | { 137 | "name": "upload-html", 138 | "pull": "always", 139 | "image": "plugins/s3-sync", 140 | "settings": { 141 | "bucket": "uploads", 142 | "endpoint": from_secret("docs_s3_server"), 143 | "access_key": from_secret("docs_s3_access_key"), 144 | "secret_key": from_secret("docs_s3_secret_key"), 145 | "path_style": "true", 146 | "source": "public/", 147 | "target": "/deploy", 148 | "delete": "true", 149 | }, 150 | "when": { 151 | "event": [ 152 | "push", 153 | "cron", 154 | ], 155 | "branch": [ 156 | deployment_branch, 157 | ], 158 | }, 159 | }, 160 | { 161 | "name": "notify", 162 | "pull": "if-not-exists", 163 | "image": "plugins/slack", 164 | "settings": { 165 | "webhook": from_secret("rocketchat_talk_webhook"), 166 | "channel": "builds", 167 | }, 168 | "when": { 169 | "event": [ 170 | "push", 171 | "cron", 172 | ], 173 | "status": [ 174 | "failure", 175 | ], 176 | }, 177 | }, 178 | ], 179 | "depends_on": [ 180 | "check-starlark", 181 | ], 182 | "trigger": { 183 | "ref": { 184 | "include": [ 185 | "refs/heads/%s" % deployment_branch, 186 | "refs/tags/**", 187 | "refs/pull/**", 188 | ], 189 | }, 190 | }, 191 | } 192 | 193 | def from_secret(name): 194 | return { 195 | "from_secret": name, 196 | } 197 | -------------------------------------------------------------------------------- /.github/dependabot.yml: -------------------------------------------------------------------------------- 1 | version: 2 2 | updates: 3 | - package-ecosystem: npm 4 | directory: "/" 5 | schedule: 6 | interval: daily 7 | time: "22:00" 8 | open-pull-requests-limit: 10 9 | -------------------------------------------------------------------------------- /.github/issue_template.md: -------------------------------------------------------------------------------- 1 | ## WHAT Needs to be Documented? 2 | 3 | 4 | ## WHERE Does This Need To Be Documented (Link)? 5 | 6 | 7 | ## WHY Should This Change Be Made? 8 | 9 | 10 | ## (Optional) What Type Of Content Change Is This? 11 | - [ ] New Content Addition 12 | - [ ] Old Content Deprecation 13 | - [ ] Existing Content Simplification 14 | - [ ] Bug Fix to Existing Content 15 | 16 | ## (Optional) Which Manual Does This Relate To? 17 | - [ ] Admin Manual 18 | - [ ] Developer Manual 19 | - [ ] User Manual 20 | - [ ] Android 21 | - [ ] iOS 22 | - [ ] Branded Clients 23 | - [ ] Desktop Client 24 | - [ ] Other 25 | 26 | -------------------------------------------------------------------------------- /.github/settings.yml: -------------------------------------------------------------------------------- 1 | repository: 2 | name: docs 3 | description: ownCloud Documentation (v2) 4 | homepage: https://doc.owncloud.com/ 5 | has_wiki: false 6 | labels: 7 | - name: 1 - To develop 8 | color: ededed 9 | - name: 2 - Developing 10 | color: ededed 11 | - name: 3 - To Review 12 | color: ededed 13 | - name: 4 - To release 14 | color: ededed 15 | - name: Acceptance tests 16 | color: ededed 17 | - name: Drone 18 | color: 6474c1 19 | - name: 'Effort: 0.5d' 20 | color: c2e0c6 21 | - name: 'Effort: 1d' 22 | color: c2e0c6 23 | - name: 'Effort: 1w' 24 | color: c2e0c6 25 | - name: 'Effort: 2d' 26 | color: c2e0c6 27 | - name: 'Effort: 2w' 28 | color: c2e0c6 29 | - name: 'Effort: 4d' 30 | color: c2e0c6 31 | - name: 'Effort: trivial' 32 | color: c2e0c6 33 | - name: Hardening 34 | color: ededed 35 | - name: PM prio 1 36 | color: fbca04 37 | - name: PM prio 2 38 | color: fbca04 39 | - name: PM prio 3 40 | color: fbca04 41 | - name: QA 42 | color: 1d76db 43 | - name: QA-blocker 44 | color: 0052cc 45 | - name: QA-known 46 | color: 0052cc 47 | - name: QA-ready 48 | color: 0052cc 49 | - name: QA-team 50 | color: 4cc948 51 | - name: QA-testing 52 | color: 0052cc 53 | - name: Sys Admin 54 | color: ededed 55 | - name: WIP 56 | color: 8c8cea 57 | - name: Waiting 58 | color: e6e6e6 59 | - name: Waiting Internal 60 | color: e6e6e8 61 | - name: Waiting On Review/Feedback 62 | color: ededed 63 | - name: Waiting on PR merge 64 | color: fc26105B2929 65 | description: This PR cannot be merged until another one is. 66 | - name: work in progress 67 | color: 9d0ED1 68 | description: Still in development. Not to be merged. 69 | - name: bug 70 | color: fc2929 71 | description: Something isn't working 72 | - name: clean up 73 | color: fc2929 74 | description: Is a clean up of some part of the existing documentation 75 | - name: bug-solved 76 | color: 0e8a16 77 | - name: clarification request 78 | color: d4c5f9 79 | - name: encryption 80 | color: AD96E8 81 | - name: dependencies 82 | color: 0025ff 83 | - name: design 84 | color: cc317c 85 | - name: discussion 86 | color: fbca04 87 | - name: enhancement 88 | color: 02e10c 89 | description: New feature or request. 90 | - name: enterprise docs 91 | color: 6040ad 92 | - name: enhancement-PM 93 | color: FF9900 94 | - name: in progress 95 | color: ededed 96 | - name: invalid 97 | color: ededed 98 | - name: junior job 99 | color: f6d300 100 | - name: needs info 101 | color: 0b02e1 102 | - name: overview 103 | color: fef2c0 104 | - name: p1-urgent 105 | color: fc2929 106 | description: Consider a hotfix release with only that fix (ex: lost trust, money, security issue, ...) 107 | - name: p2-high 108 | color: fc2929 109 | description: Escalation, on top of current planning, release blocker. 110 | - name: p3-medium 111 | color: fc2929 112 | description: Normal priority. 113 | - name: p4-low 114 | color: fc2929 115 | description: Low priority. 116 | - name: pdf generation 117 | color: 330272 118 | description: Anything related to the generation of the PDF manuals. 119 | - name: packaging 120 | color: F7C6C7 121 | - name: performance 122 | color: fbca04 123 | - name: ready 124 | color: ededed 125 | - name: regression 126 | color: e11d21 127 | - name: release note 128 | color: BFD4F2 129 | - name: research 130 | color: FFFF00 131 | - name: review carefully! 132 | color: ededed 133 | - name: security 134 | color: 02d7e1 135 | - name: technical debt 136 | color: FFFF00 137 | - name: tested 138 | color: FBCA04 139 | - name: won't fix 140 | color: ffffff 141 | - name: admin docs 142 | color: 0847A5 143 | - name: APIs 144 | color: FCDCC7 145 | - name: desktop client docs 146 | color: 7108D3 147 | - name: iOS client docs 148 | color: 530D89 149 | - name: Android client docs 150 | color: 530D89 151 | - name: developer docs 152 | color: B7D653 153 | - name: enterprise docs 154 | color: B7D653 155 | - name: user docs 156 | color: B7D653 157 | - name: duplicate 158 | color: CFD3D7 159 | - name: invalid 160 | color: E4E669 161 | description: This doesn't seem right 162 | - name: analytics 163 | color: B522CC 164 | - name: LDAP 165 | color: 6341B5 166 | description: Relates to LDAP interaction and integration with ownCloud. 167 | - name: logging 168 | color: 4EE8D1 169 | - name: appliance 170 | color: 9B99DD 171 | - name: backport 172 | color: 9551B5 173 | - name: blocked 174 | color: 4938AA 175 | - name: command-line 176 | color: 3F1E99 177 | description: Documentation relates to the command-line. 178 | - name: deprecation 179 | color: B7DEF4 180 | description: Involves removing existing content that is no longer valid. 181 | - name: help wanted 182 | color: 008672 183 | description: Extra attention is needed. 184 | - name: good first issue 185 | color: CCCC33 186 | description: Good task for newcomers. 187 | - name: outdated documentation 188 | color: B1DEED 189 | description: Update or remove outdated documentation. 190 | - name: question 191 | color: D876E3 192 | description: Further information has been requested. 193 | - name: training 194 | color: 6A737D 195 | description: Training and educational resources for contributors. 196 | - name: installation and configuration 197 | color: 390B93 198 | - name: Marketplace 199 | color: 6341B5 200 | description: Anything related to the ownCloud Marketplace. 201 | - name: no backport 202 | color: 8C043A 203 | - name: occ 204 | color: 59039B 205 | - name: seo 206 | color: 59039B 207 | - name: deployment 208 | color: E89D53 209 | description: Tasks relating to deploying the documentation. 210 | - name: database 211 | color: 9C1EFC 212 | description: Anything related to databases. 213 | - name: shares 214 | color: B87FF4 215 | - name: waiting on PR merge 216 | - name: occ 217 | color: E697F4 218 | description: Anything related to the occ command. 219 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | site-dev.yml 2 | yarn-error.log 3 | cache/ 4 | node_modules/ 5 | public/ 6 | pdf_web/ 7 | tmp/ 8 | .DS_Store 9 | .vscode/ 10 | .idea/ 11 | -------------------------------------------------------------------------------- /.prettierrc: -------------------------------------------------------------------------------- 1 | { 2 | "printWidth": 99, 3 | "singleQuote": true, 4 | "semi": false, 5 | "trailingComma": "none" 6 | } 7 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # ownCloud Documentation 2 | 3 | [![Build Status](http://drone.owncloud.com/api/badges/owncloud/docs/status.svg?branch=master)](http://drone.owncloud.com/owncloud/docs) 4 | 5 | 1. The platform and tools used to build the documentation is [Antora](./docs/what-is-antora.md). 6 | 2. The file format that the documentation is written in is [AsciiDoc](./docs/what-is-asciidoc.md). 7 | 3. The UI & UX of the documentation can be found at [docs-ui](https://github.com/owncloud/docs-ui) 8 | 9 | **Table of Contents** 10 | 11 | * [Antora Site Structure for Docs](#antora-site-structure-for-docs) 12 | * [Extensions](#extensions) 13 | * [Documentation Guidelines](#documentation-guidelines) 14 | * [Contributing to the Documentation](#contributing-to-the-documentation) 15 | * [Generating the Documentation](#generating-the-documentation) 16 | * [Common Content and Styling the Documentation](#common-content-and-styling-the-documentation) 17 | * [Best Practices and Tips](#best-practices-and-tips) 18 | * [Target Branch and Backporting](#target-branch-and-backporting) 19 | * [When Does a Change Get Published to the Docs Web Site?](#when-does-a-change-get-published-to-the-docs-web-site) 20 | * [Create a New Version Branch for Docs](#create-a-new-version-branch-for-docs) 21 | * [HTML to PDF](#html-to-pdf) 22 | 23 | ## Antora Site Structure for Docs 24 | 25 | Refer to the [Antora Site Structure for Docs](./docs/antora-site-structure.md) for more information. 26 | 27 | ## Extensions 28 | 29 | The documentation intensively uses Antora/Asciidoc extensions. These extensions enrich the base functionality with additional and required capabilities. Read the [extensions](./docs/extensions.md) documentation for more information. 30 | 31 | ## Documentation Guidelines 32 | 33 | Refer to the [Documentation Guidelines](./docs/doc-guidelines.md) for more information about backgrounds and processes. 34 | 35 | ## Contributing to the Documentation 36 | 37 | To get started contributing to the documentation, please refer to the [Getting Started Guide](./docs/getting-started.md). 38 | 39 | With regard to language and style issues, consult the [Style Guide](./docs/style-guide.md). 40 | 41 | Note that the documentation provides a setting for the [IntelliJ AsciiDoc-Antora Plugin](https://intellij-asciidoc-plugin.ahus1.de) to preview a page using the css sourced from `doc.owncloud.com`. The file required containing the necessary configuration is `.asciidoctorconfig`. 42 | 43 | ## Generating the Documentation 44 | 45 | **IMPORTANT** 46 | We use `node 18.19.0`. In case you used a lower node version for your local doc repos, you must upgrade them **all**. See the link below for details. 47 | 48 | **IMPORTANT** 49 | We use `Antora 3.1.10` and use npm instead of yarn. In case you used a lower Antora version for your local doc repos, you must upgrade them **all** by syncing them and running `npm install` in each doc repo. 50 | 51 | To generate and view the documentation locally or planning major changes, refer to the [Building the Documentation guide](./docs/build-the-docs.md). 52 | 53 | ## Common Content and Styling the Documentation 54 | 55 | If you want to suggest an improvement to the ownCloud documentation theme, such as the layout, the header or the footer text, or if you find a bug, all the information that you need is in the `docs-ui` repository. Changes made in `docs-ui` are valid for the whole documentation. 56 | 57 | Please read how to test un-merged [docs-ui](./docs/test-ui-bundle.md) changes with content from the ownCloud documentation. 58 | 59 | ## Best Practices and Tips 60 | 61 | Refer to [Best Practices and Tips for writing in AsciiDoc](./docs/best-practices.md) for more information. 62 | 63 | To check for broken links manually, see [install and use a broken-link-checker](./docs/checking-broken-links.md). 64 | 65 | ## Target Branch and Backporting 66 | 67 | Please always do your changes in `master` and backport them to the relevant branches. 68 | The **ONLY** reason for doing a PR in a branch directly is, to fix an issue which is 69 | _only_ present in that particular branch! When creating a PR and it is necessary to backport, 70 | document in the PR to which branches a backport is needed. 71 | 72 | When backporting, consider using the [backport script](./docs/getting-started.md#backporting) 73 | which eases life a lot and speeds up the process. It is also very beneficial when using the 74 | extended code provided, because a clear naming structure of the backport PR is generated automatically. 75 | 76 | ## When Does a Change Get Published to the Docs Web Site? 77 | 78 | Changes made will get published to the web under the following conditions: 79 | 80 | 1. A merge in a component to one of the defined version branches triggers as a last step a master branch build. 81 | 2. A merge to master triggers a site build which then pushes all versions defined in site.yml. 82 | 83 | ## Create a New Version Branch for Docs 84 | 85 | Please refer to [Create a New Version Branch for Docs](./docs/new-version-branch.md) for more information. 86 | 87 | ## HTML to PDF 88 | 89 | At the moment, creating a pdf is dropped from the build process but can be re-implemented if required. 90 | -------------------------------------------------------------------------------- /bin/git_commands/backport.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | # version 2024.06.05 3 | # backport the given merge SHA to the branch provided 4 | 5 | if ! [ -x "$(command -v jq)" ]; then 6 | echo 7 | echo 'Error: jq is not installed.' >&2 8 | echo 'Please install package "jq" before using this script' 9 | echo 10 | exit 1 11 | fi 12 | 13 | if ! [ -x "$(command -v curl)" ]; then 14 | echo 15 | echo 'Error: curl is not installed.' >&2 16 | echo 'Please install package "curl" before using this script' 17 | echo 18 | exit 1 19 | fi 20 | 21 | if [ "$#" -lt 2 ]; then 22 | echo 23 | echo "Illegal number of parameters" 24 | echo " $0 " 25 | echo " For example: $0 1234567 10.8" 26 | echo 27 | exit 1 28 | fi 29 | 30 | commit=$1 31 | targetBranch=$2 32 | sourceBranch=$(git rev-parse --abbrev-ref HEAD) 33 | 34 | # check if the target branch exists on remote to avoid backporting to a non existing remote branch 35 | exists_in_remote=$(git ls-remote --heads origin ${targetBranch}) 36 | if [ -z "${exists_in_remote}" ]; then 37 | echo 38 | echo "Branch ${targetBranch} does not exist on remote. Create it first. Exiting" 39 | echo 40 | exit 1 41 | fi 42 | 43 | # check if the target branch already exists locally 44 | exists_in_local=$(git branch --list ${targetBranch}) 45 | if [ -z "${exists_in_local}" ]; then 46 | echo 47 | echo "Branch ${targetBranch} does not exist locally. Make it available first. Exiting" 48 | echo 49 | exit 1 50 | fi 51 | 52 | # check if the given merge commit exists in the actual checked out branch 53 | is_merged=$(git branch --contains $1 2>/dev/null | grep -oP '(?<=\*).*') 54 | if [ -z "${is_merged}" ]; then 55 | echo 56 | echo "${commit} does not exist because:" 57 | echo "- the PR has not been merged yet or" 58 | echo "- your actual backporting base branch ${sourceBranch} is not pulled/rebased." 59 | echo "Exiting" 60 | echo 61 | exit 1 62 | fi 63 | 64 | # get the PR number from the merge commit 65 | # there can be a PR reference text in the commit like "fixes #1234". 66 | # we only need to take the last line which is then the real PR # the commit belongs to 67 | pullId=$(git log $1^! --oneline 2>/dev/null | tail -n 3 | grep -oP '(?<=#)[0-9]*' | tail -n 1) 68 | 69 | # get the repository from the given commit 70 | # remove prefix and suffix from the full url returned 71 | repository=$(git config --get remote.origin.url 2>/dev/null) 72 | repository=${repository#"https://github.com/"} 73 | repository=${repository%".git"} 74 | 75 | # get the list of commits in PR without any merge commit 76 | # $1^ means the first parent of the merge commit (that is passed in as $1). 77 | # because $1 is a "magically-generated" merge commit, it happily "jumps back" 78 | # to the point on the main branch just before where the PR was merged. 79 | # the commits from that point are exactly the list of individual 80 | # commits in the original PR. 81 | # --no-merges leaves out the merge commit itself, and we get just what we want 82 | commitList=$(git log --no-merges --reverse --format=format:%h $1^..$1) 83 | 84 | # get the request reset time window from github in epoch 85 | rateLimitReset=$(curl -iks https://api.github.com/users/zen 2>&1 | grep -im1 'X-Ratelimit-Reset:' | grep -o '[[:digit:]]*') 86 | 87 | # get the remaining requests in window from github 88 | rateLimitRemaining=$(curl -iks https://api.github.com/users/zen 2>&1 | grep -im1 'X-Ratelimit-Remaining:' | grep -o '[[:digit:]]*') 89 | 90 | # time remaining in epoch 91 | now=$(date +%s) 92 | ((remaining=rateLimitReset-now)) 93 | 94 | # time remaining in HMS 95 | remaining=$(date -u -d @${remaining} +%H:%M:%S) 96 | 97 | # echo one time for a good rendering 98 | echo 99 | 100 | # check if there are commits to cherry pick and list them if present 101 | if [[ -z "${commitList}" ]]; then 102 | echo "There are no commit(s) to cherry pick. Exiting" 103 | echo 104 | exit 1 105 | else 106 | lineCount=$(echo "${commitList}" | grep '' | wc -l) 107 | echo "${lineCount} commit(s) to be cherry picked:" 108 | echo 109 | echo "${commitList}" 110 | echo 111 | fi 112 | 113 | if [ ${rateLimitRemaining} -le 0 ]; then 114 | # do not continue if there are no remaining github requests available 115 | echo 116 | echo "You do not have enough github requests available to backport" 117 | echo "The current rate limit window resets in ${remaining}" 118 | echo 119 | exit 1 120 | else 121 | # get the PR title, this is the only automated valid way to get the title 122 | pullTitle=$(curl https://api.github.com/repos/"${repository}"/pulls/"${pullId}" 2>/dev/null | jq '.title' | sed 's/^.//' | sed 's/.$//') 123 | # remove possible line breaks on any location in the string 124 | pullTitle=${pullTitle//$'\n'/} 125 | fi 126 | 127 | # build variables for later use 128 | newBranch="${targetBranch}-${commit}-${pullId}" 129 | message="[${targetBranch}] [PR ${pullId}] ${pullTitle}" 130 | 131 | # first check, if the source branch is clean and has no uncommited changes 132 | # in case this is true, checkout does not succeed and nothing needs to be done/switched 133 | # xargs removes any possible leading and trailing whitespaces 134 | is_source_branch_clean=$(git status --porcelain=v1 2>/dev/null | xargs) 135 | if [[ ! -z "${is_source_branch_clean}" ]]; then 136 | echo "Source branch ${sourceBranch} has probably uncommitted changes. Aborting." 137 | echo 138 | exit 1 139 | fi 140 | 141 | # exit the script if any statement returns a non-true return value 142 | # means that all commands from now on must run successfully 143 | set -e 144 | 145 | # fetch branches and/or tags from one or more other repositories, along with the 146 | # objects necessary to complete their histories 147 | git fetch -p --quiet 148 | 149 | # checkout and rebase the target branch 150 | git checkout "${targetBranch}" --quiet 151 | 152 | # if everything is ok, then rebase the target branch 153 | git pull --rebase --quiet 154 | 155 | # create a new branch based on the target branch 156 | # the new branch name equals the new commit name 157 | git checkout -b "${newBranch}" "${targetBranch}" 158 | 159 | echo 160 | 161 | # cherry pick all commits from commitList 162 | lC=1 163 | echo "${commitList}" | while IFS= read -r line; do 164 | # start cherry-picking 165 | echo "Cherry picking commit ${lC}: ${line}" 166 | 167 | # check if the commit to be cherry picked is already in the branch 168 | # this only works if the commit was cherry picked before! 169 | # else it will just try and continue. 170 | is_cherry_picked=$(git log --grep "${line}" 2>/dev/null) 171 | if [[ ! -z "${is_cherry_picked}" ]]; then 172 | echo 173 | echo "Commit ${line} has already been cherry picked, abort backporting." 174 | # go back to the base branch and delete the new branch with all its contents. 175 | git checkout --quiet "${sourceBranch}" 176 | git branch -D --quiet "${newBranch}" 177 | echo 178 | exit 1 179 | fi 180 | 181 | # pull this commit into the new branch 182 | # --allow-empty is required if an empty commit is present like when when retriggering the CI. 183 | # if you do not want to use a default conflict resolution to take theirs 184 | # (help fix missing cherry picked commits or file renames) 185 | #git cherry-pick --allow-empty ${line} > /dev/null 186 | git cherry-pick --allow-empty -Xtheirs "${line}" > /dev/null 187 | lC=$(( ${lC} + 1 )) 188 | done 189 | 190 | echo 191 | echo "Committing changes" 192 | echo 193 | 194 | ## rewrite the most recent commit message 195 | ## the first -m creates the PR headline text 196 | ## the second -m creates the PR message text 197 | git commit --allow-empty --quiet --amend -m "${message}" -m "Backport of PR #${pullId}" 198 | 199 | echo "Pushing: ${message}" 200 | echo 201 | 202 | git push --quiet -u origin "${newBranch}" 203 | git checkout --quiet "${sourceBranch}" 204 | 205 | # open the browser and prepare the pull request 206 | echo 207 | sleep 4 208 | echo "Creating pull request for branch ${targetBranch} in ${repository}" 209 | xdg-open "https://github.com/${repository}/pull/new/${targetBranch}...${newBranch}" &>/dev/null 210 | -------------------------------------------------------------------------------- /bin/git_commands/getcommits.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | 3 | echo "count branch commits compared against master or the branch name if provided" 4 | git rev-list --count HEAD ^"${1:-master}" 5 | -------------------------------------------------------------------------------- /bin/git_commands/getpull.sh: -------------------------------------------------------------------------------- 1 | #!/bin/sh 2 | 3 | # try to identify the pull request that was created for the commit ID provided 4 | 5 | if [ -z "$1" ]; then 6 | echo "Usage: git getpull " 7 | exit 1 8 | elif [ -z "$(git rev-parse --git-dir 2>/dev/null)" ]; then 9 | echo "Not in a git directory" 10 | exit 1 11 | else 12 | repository_path=$(git config --get remote.origin.url 2>/dev/null | perl -lne 'print $1 if /(?:(?:https?:\/\/github.com\/)|:)(.*?).git/') 13 | pull_base_url=https://github.com/$repository_path/pull 14 | pull_id=$(git log $1^! --oneline 2>/dev/null | tail -n 3 | grep -oP '(?<=#)[0-9]*') 15 | # pull_id=$(git log $1..master --ancestry-path --merges --oneline 2>/dev/null | tail -n 1 | perl -nle 'print $1 if /#(\d+)/') 16 | 17 | # if [ -n "$pull_id" ]; then 18 | echo "$pull_base_url/$pull_id" 19 | # else 20 | # echo "Sorry, couldn't find that pull" 21 | # exit 1 22 | # fi 23 | fi 24 | 25 | -------------------------------------------------------------------------------- /bin/git_commands/squash.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | # squash the number of commits to one with a defined commit message 3 | 4 | #get number of commits to squash 5 | squashCount=$1 6 | 7 | #get the commit message 8 | shift 9 | commitMsg=$@ 10 | 11 | #regular expression to verify that squash number is an integer 12 | regex='^[0-9]+$' 13 | 14 | echo "---------------------------------" 15 | echo "Will squash $squashCount commits" 16 | echo "Commit message will be '$commitMsg'" 17 | 18 | echo "...validating input" 19 | 20 | if ! [[ $squashCount =~ $regex ]] 21 | then 22 | echo "Squash count must be an integer." 23 | elif [ -z "$commitMsg" ] 24 | then 25 | echo "Invalid commit message. Make sure string is not empty" 26 | else 27 | echo "...input looks good" 28 | echo "...proceeding to squash" 29 | git reset --soft HEAD~$squashCount 30 | git commit -m "$commitMsg" 31 | echo "...done" 32 | fi 33 | 34 | 35 | 36 | echo 37 | 38 | exit 0 39 | 40 | -------------------------------------------------------------------------------- /bin/manual_config_pdf: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env bash 2 | 3 | # if there is manual in the available manuals array below, 4 | # the manual directory is set to ROOT and not the manual name dynamically generated from the array list 5 | # also, set in that case the postfix_name to "" and have the manual name like you want to print it (e.g. "Desktop_Client") 6 | # only change ROOT in case you know what you are doing 7 | # be aware that a manual name MUST NOT contain a blank 8 | MANUAL_ROOT_NAME="ROOT" 9 | # the postfix component is used to create the path to the manual like admin_manual 10 | MANUAL_POSTFIX_NAME="_manual" 11 | # note that this name must be part of the book filename in books/ 12 | # a part of the file name is composed by available_manuals+manual_postfix 13 | AVAILABLE_MANUALS=(admin user developer) 14 | # define if the first letter of the manual name must be captitalized (Desktop) 15 | # make empty in case it can be also lower case (like iOS-App) 16 | FIRST_LETTER_CAPITAL="Y" 17 | -------------------------------------------------------------------------------- /bin/optimize_crawl: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env bash 2 | 3 | # optimizes sitemap-xxx.xml and robots.txt for improved crawling as we only need references to "next" urls. 4 | # 5 | # 1.) deletes in all sitemap-.xml files all xml blocks not containing the term "next" (DEFAULT_NAME) 6 | # post the product name. this is done only for only those xml files, which have the new docs structure 7 | # containing "next" as part of the url for the master branch. 8 | # 9 | # 2.) if uncommented in the code, adds at the end of the robots.txt file "Disallow" directives for all 10 | # non "next" urls/* which match the new docs structure containing "next", e.g. Disallow: /server/10.8/* 11 | # 12 | # the script is intended to be called from the root of this repo. 13 | # 14 | # see the "PRODUCTS" variable for eligable repos 15 | # 16 | # note, no file should be created manually or by an other process with the extension defined in BACKUP_EXT. 17 | # 18 | # 19 | # SEE IMPORTANT COMMENT AT ABOUT LINE 200 20 | 21 | set -e 22 | set -u 23 | set -o noclobber 24 | set -o errexit 25 | set -o pipefail 26 | set -o nounset 27 | IFS=$'\n\t' 28 | 29 | # these are the products which have the new doc structure using a version, at minimum 'next'. 30 | # only those are taken for optimisation! 31 | # the name must be identical to the name tag in antora.yml of the particular doc repo. 32 | PRODUCTS=(docs server ocis webui desktop ios-app android branding) 33 | 34 | # the location where the site is built to 35 | HTML_ROOT="public" 36 | 37 | # the name of the master sitemap file 38 | # this file includes all other sitemaps 39 | SITEMAP="sitemap.xml" 40 | 41 | # define common variables 42 | ACTION= 43 | DOC_WEB_ROOT= 44 | SITEMAPS_TO_USE= 45 | DRY_RUN=false 46 | 47 | # note that the extension must include the leading dot 48 | BACKUP_EXT=".original" 49 | 50 | # the default name is the name used when the branch is master. 51 | # only for those products which have the new doc structure. 52 | DEFAULT_NAME="next" 53 | 54 | # error variables 55 | ERR_UNSUPPORTED_ACTION=22 56 | 57 | SITEMAP_ROOT_FILE="${HTML_ROOT}/${SITEMAP}" 58 | 59 | # the main function which processes all files 60 | function run() 61 | { 62 | local i= 63 | local url= 64 | local hit= 65 | local first= 66 | local actual=() 67 | local product_name= 68 | local current_map= 69 | local current_robot= 70 | local product_name= 71 | local unuseable_releases=() 72 | local sitemap_header= 73 | local url_component_ok= 74 | local new_xml_content= 75 | local add_robot_content= 76 | 77 | current_robot="${HTML_ROOT}/robots.txt" 78 | 79 | # find all files in the html root dir, and only there, where the extension is backup_ext 80 | # if found, those files should be reverted back to the original state before continue executing 81 | for i in `find "${HTML_ROOT}" -maxdepth 1 -name "*${BACKUP_EXT}" -type f`; do 82 | hit=true 83 | done 84 | if [ "$hit" = true ]; then 85 | echo 86 | echo -e "\e[1;31mThere were files found indicating a past run. \e[0m" 87 | echo -e "\e[1;31mRevert them first. \e[0m" 88 | usage 89 | exit $ERR_UNSUPPORTED_ACTION 90 | fi 91 | 92 | echo -e "\e[1;32mOptimizing \e[0m" 93 | echo 94 | 95 | # changes in the robots file only when not in debug mode 96 | if [[ "$DRY_RUN" == false ]]; then 97 | # create a copy of the robots file to make a backup 98 | cp "${current_robot}" "${current_robot}${BACKUP_EXT}" 99 | 100 | # add a blank line for better visibility to the following disallows 101 | # (not using $'\n'... becomes a double blank line when used alone) 102 | cat <<< "" >> "${current_robot}" 103 | fi 104 | 105 | # get the current existing docs url from sitemap.xml 106 | get_doc_www_root "${SITEMAP_ROOT_FILE}" 107 | 108 | # get the list of sitemaps to process 109 | get_sitemaps "${SITEMAP_ROOT_FILE}" "${PRODUCTS[@]}" 110 | #printf '%s\n' "${SITEMAPS_TO_USE[@]}" 111 | 112 | # iterate over all sitemap files 113 | for current_map in "${SITEMAPS_TO_USE[@]}" 114 | do 115 | 116 | new_xml_content= 117 | 118 | #echo "${current_map}" 119 | # get the product name of the current iterating map 120 | product_name=($(get_product_name "${current_map}")) 121 | # echo "$product_name" 122 | 123 | # get all the releases we do not need to keep 124 | unuseable_releases=($(get_unuseable_releases "${current_map}")) 125 | # printf '%s\n' "${unuseable_releases[@]}" 126 | 127 | # keep this, for testing purposes only 128 | # # get the header of the sitemap file 129 | # sitemap_header=$(get_sitemap_header "${current_map}") 130 | # #echo "$sitemap_header" 131 | 132 | url_component_ok="${DOC_WEB_ROOT}"/"${product_name}"/"${DEFAULT_NAME}"/ 133 | 134 | i=-1 135 | url=false 136 | hit=false 137 | first=true 138 | unset actual 139 | 140 | # read the current xml file and remove all non-"next" entries 141 | while read line; do 142 | i=$((i+1)) 143 | actual[$i]="${line}" 144 | 145 | # starting the block. we expect that are in seperate lines 146 | if [[ "${line}" == "" ]]; then 147 | url=true 148 | first=false 149 | else 150 | # get all lines before the first , there is always necessary stuff above to be taken 151 | # we do not need an array here but add the lines one by one 152 | if [ "$first" = true ]; then 153 | new_xml_content="${new_xml_content}""${line}"$'\n' 154 | # unset the array to remove any leftovers for the first match of 155 | # necessary as we do not know if the first url block will be a hit or not 156 | unset actual 157 | #printf '%s\n' "${new_xml_content[@]}" 158 | continue 159 | fi 160 | fi 161 | 162 | # we are inside a block 163 | if [ "$url" = true ]; then 164 | # check if it is a block 165 | if [[ "${line}" == ""* ]]; then 166 | # check if it contains a usable url with "next" 167 | if [[ "${line}" == *"${url_component_ok}"* ]]; then 168 | hit=true 169 | #echo "${line}" 170 | fi 171 | fi 172 | fi 173 | 174 | # at the end of the block 175 | if [[ "${line}" == "" ]]; then 176 | # use only if we have a hit 177 | if [ "$hit" == true ]; then 178 | #printf '%s\n' "${actual[@]}" 179 | new_xml_content="${new_xml_content}"$(printf '%s\n' "${actual[@]}")$'\n' 180 | fi 181 | # if we had a hit, reset all 182 | i=-1 183 | url=false 184 | hit=false 185 | unset actual 186 | fi 187 | 188 | done < "${current_map}" 189 | 190 | # finally, add all the remaining elements which are post the last 191 | # the last actual array contains all lines after the last 192 | new_xml_content="${new_xml_content}"$(printf '%s\n' "${actual[@]}") 193 | 194 | # create a disallow entry for the particular product containig non- "next" entries 195 | unset actual 196 | add_robot_content= #$'\n' 197 | for actual in "${unuseable_releases[@]}" 198 | do 199 | #echo $actual 200 | url_component_ok=/"${product_name}"/"${actual}"/* 201 | # 202 | # NOTE the following script line is temporarily commented. 203 | # 204 | # Google can't reindex a site where robots.txt disallows urls which are, when accessed, redirected to a disallowed 205 | # page, even robots.txt is valid and does not disallow the site itself. 206 | # 207 | # robots.txt --> disallow: /server/10.8/* 208 | # docs.owncloud.com --> docs.owncloud.com/server/latest --> docs.owncloud.com/server/10.8 (** bang **) 209 | # 210 | # when server gets its own repository and the main site entry does not automatically redirect to server/latest, 211 | # this comment can be removed and the disallow is added again. 212 | # 213 | # add_robot_content="${add_robot_content}""Disallow: ""${url_component_ok}"$'\n' 214 | done 215 | 216 | # echo the output in debug mode but do not do anything else 217 | # make the headline green for better identification of the current xml file 218 | if [[ "$DRY_RUN" == true ]]; then 219 | echo 220 | echo -e "\e[1;32m${current_map} \e[0m" 221 | echo 222 | echo "${new_xml_content}" 223 | echo 224 | echo -e "\e[1;32mTo be added to ${HTML_ROOT}/robots.txt\e[0m" 225 | echo "${add_robot_content}" 226 | else 227 | # write the changes to the files 228 | # backup the current sitemap file 229 | mv "${current_map}" "${current_map}${BACKUP_EXT}" 230 | # create a new sitemap file and write the new contents 231 | cat <<< "$new_xml_content" > "$current_map" 232 | # append the contents to the new robots file 233 | cat <<< "$add_robot_content" >> "${current_robot}" 234 | fi 235 | 236 | # for testing to make only one block 237 | # break 238 | done 239 | 240 | # remove any emtpy lines at the END of the script 241 | # this keeps the content compact if not adding disallows 242 | sed -i -e :a -e '/^\n*$/{$d;N;ba' -e '}' "${current_robot}" 243 | 244 | } 245 | 246 | # get the header lines of the current sitemap file 247 | function get_sitemap_header() 248 | { 249 | # example 250 | # 251 | # 252 | local sh= 253 | sh=$(sed '//Q' "$1") 254 | echo "${sh}" 255 | } 256 | 257 | # get all unusabe releases of the current sitemap file 258 | function get_unuseable_releases() 259 | { 260 | local a=() 261 | local ur=() 262 | 263 | # make an array of the default name to intersect with the existing names 264 | local name=( "${DEFAULT_NAME}" ) 265 | 266 | ur=($(grep -oP '(?<=loc>)[^<]+' "$1" | grep -Po '\w\K/\w+[^?]+' | cut -c 2- | cut -d \/ -f 2 | sort | uniq)) 267 | 268 | # intersect the arrays 269 | # the array must be returned in this case with printf and not with echo 270 | readarray -t a < <(echo ${ur[@]} ${name[@]} | tr ' ' '\n' | sort | uniq -d | xargs echo ${ur[@]} | tr ' ' '\n' | sort | uniq -u) 271 | printf '%s\n' "${a[@]}" 272 | } 273 | 274 | # get the product name of a particular sitemap file 275 | function get_product_name() 276 | { 277 | local pn= 278 | pn=($(grep -oP '(?<=loc>)[^<]+' "$1" | grep -Po '\w\K/\w+[^?]+' | cut -c 2- | cut -d \/ -f 1 | uniq)) 279 | echo "${pn}" 280 | } 281 | 282 | # query the URL of the docs site. 283 | # this can also be a local address (e.g. ip:port) if you have built e.g. with "yarn antora-local". 284 | # will be used to identify a deletable block in a sitemap file 285 | function get_doc_www_root() 286 | { 287 | DOC_WEB_ROOT=($(grep -oP '(?<=loc>)[^<]+' "$1" | cut -d/ -f1-3 |uniq)) 288 | #echo "${DOC_WEB_ROOT}" 289 | } 290 | 291 | # get_sitemaps 292 | # get all sitemap files which are available and match the product array list 293 | # using parameters helps customizing the function easily 294 | function get_sitemaps() 295 | { 296 | local a=() # helper variable 297 | local sitemap_base_file="$1" # Save first argument in a variable 298 | shift # Shift all arguments to the left (original $1 gets "lost") 299 | local b=("$@") # Rebuild the products array with rest of arguments 300 | local found_sitemaps=() # the list of sitemap files found 301 | 302 | # append .xml to each availabe product and sort the outcome 303 | a=( "${b[@]/%/.xml}" ) 304 | readarray -t available_products < <(printf '%s\n' "${a[@]}" | sort) 305 | #printf '%s\n' "${available_products[@]}" 306 | 307 | # get the list of referenced sitemaps from the main sitemap file and store it into an array 308 | # the name is stored without the extension ".xml" 309 | # the files are defined inbetween the tags 310 | # for matching the arrays, we need to remove the leading "sitemap-" string 311 | readarray -t found_sitemaps < <(grep -oP '(?<=loc>)[^<]+' "${sitemap_base_file}" | grep -Po '\w\K/\w+[^?]+' | cut -c 2- | sed 's/sitemap-//g' | sort) 312 | #printf '%s\n' "${found_sitemaps[@]}" 313 | 314 | # Intersection of possible and available sitmap files 315 | readarray -t a < <(echo ${available_products[@]} ${found_sitemaps[@]} | tr ' ' '\n' | sort | uniq -d) 316 | a=( "${a[@]/#/sitemap-}" ) 317 | #printf '%s\n' "${a[@]}" 318 | SITEMAPS_TO_USE=( "${a[@]/#/${HTML_ROOT}/}" ) 319 | #printf '%s\n' "${SITEMAPS_TO_USE[@]}" 320 | } 321 | 322 | # rename all files with the extension ${BACKUP_EXT} back to its original extension. 323 | # this is only when playing around and you do not want to manually type all the commands 324 | function revert() 325 | { 326 | local f= 327 | 328 | echo 329 | # find all files in the html root dir, and only there, where the extension is backup_ext 330 | for f in `find "${HTML_ROOT}" -maxdepth 1 -name "*${BACKUP_EXT}" -type f`; do 331 | # move the file by removing the backup extension 332 | mv -- "${f}" "${f%${BACKUP_EXT}}" 333 | echo -e "\e[1;32mReverting file: \e[0m" "${f}" 334 | #echo "${f%${BACKUP_EXT}}" 335 | #echo "$f" 336 | done 337 | # if f is empty there was nothing found to be reverted 338 | if [ -z "$f" ]; then 339 | echo -e "\e[1;32mNothing found to be reverted \e[0m" "${f}" 340 | fi 341 | echo 342 | } 343 | 344 | function revert_and_run() 345 | { 346 | revert 347 | run 348 | } 349 | 350 | function usage() 351 | { 352 | echo 353 | echo "Usage: bin/optimize_crawl [-h] [-e] [-x] [-d] [-r]" 354 | echo 355 | echo "-h ... help" 356 | echo "-e ... Execute (add debug mode for a dry run)" 357 | echo "-x ... Revert first and Execute (add debug mode for a dry run)" 358 | echo "-d ... Debug mode, print only of the optimized sitmap content, no saving." 359 | echo "-r ... Revert backuped files to originals if exists." 360 | echo 361 | } 362 | 363 | while getopts ":rdexh:" o 364 | do 365 | case ${o} in 366 | r) 367 | ACTION="REVERT" 368 | ;; 369 | d ) 370 | DRY_RUN=true 371 | ;; 372 | e) 373 | ACTION="RUN" 374 | ;; 375 | x) 376 | ACTION="REVERT_AND_RUN" 377 | ;; 378 | h | * ) 379 | ACTION="HELP" 380 | ;; 381 | esac 382 | done 383 | 384 | shift $((OPTIND-1)) 385 | 386 | case "$ACTION" in 387 | REVERT) 388 | revert 389 | ;; 390 | RUN) 391 | run 392 | ;; 393 | REVERT_AND_RUN) 394 | revert_and_run 395 | ;; 396 | HELP | *) 397 | usage 398 | exit $ERR_UNSUPPORTED_ACTION 399 | ;; 400 | esac 401 | -------------------------------------------------------------------------------- /bin/ownCloudDocPdf.py: -------------------------------------------------------------------------------- 1 | #! /usr/bin/python3 2 | # 3 | # ownCloudDocPDF.py 4 | # 5 | # Generate a PDF version by traversing the web rendering. 6 | # This is a workaround for the currently not implemented PDF export of Antora 3. 7 | # 8 | # (c) 2023 Elcin Asgarov, 2024 Jürgen Weigert 9 | # Distribute under GPLv2 or ask. 10 | 11 | # v0.2 2024-04-24, jw Output PDF name is derived from the given URL, 12 | # EndIndex introduced, so that e.g. the admin manual does not continue into the developer manual. 13 | # Default format is A4, but changing this to Legal avoids empty pages. Somehting is odd with our footer. 14 | # v0.1 2023-09-27 Initial draft 15 | 16 | import os 17 | import re 18 | import requests 19 | import subprocess 20 | from urllib.parse import urljoin 21 | import sys 22 | import tempfile 23 | import shutil 24 | 25 | next_search_pattern = r' [] 34 | 35 | Examples: 36 | python {sys.argv[0]} https://doc.owncloud.com/webui/next/classic_ui/ 37 | python {sys.argv[0]} https://doc.owncloud.com/server/10.14/admin_manual 167 38 | 39 | Starting with the given URL, a list of "next" URLs is generated, by searching for {next_search_pattern} 40 | The list ends, when the page content does not contain a next url. 41 | You can optionally specify an EndIndex, this limits how many URLs will be processed in total. 42 | 43 | The resulting PDF file will be named like the given URL with https:// removed and some characters replaced. 44 | """) 45 | sys.exit() 46 | 47 | url = sys.argv[1] 48 | endindex = 0 49 | if len(sys.argv) > 2: 50 | endindex = int(sys.argv[2]) 51 | print(f" ... will stop after {endindex} urls") 52 | urls = [] 53 | 54 | # Creating a temporary directory 55 | temp_directory = tempfile.mkdtemp() 56 | 57 | # output_pdf = "output.pdf" 58 | ## convert 'https://doc.owncloud.com/server/10.14/admin_manual/' 59 | # into doc-owncloud-com_server_10-14_admin_manual 60 | output_base = '_'.join(url.replace('.', '-').rstrip('/').split('/')[2:]) 61 | output_pdf = output_base + '.pdf' 62 | 63 | counter = 1 64 | while os.path.exists(output_pdf): # check if file already exists 65 | # If exists, change the filename 66 | output_pdf = f"{output_base}({counter}).pdf" 67 | counter += 1 68 | 69 | print(f"Output file: {output_pdf}\n") 70 | 71 | print(f"{len(urls)+1}: {url}") 72 | while url: 73 | response = requests.get(url) 74 | body = response.text 75 | 76 | # Add current URL to the list 77 | urls.append(url) 78 | 79 | if endindex and len(urls) >= endindex: 80 | break 81 | 82 | # Step 2: Find next URL 83 | next_url_match = re.search(r' - url: ../docs-ocis.git 23 | echo "Replacing component URL paths to local paths" 24 | sed -i 's#- url: https://github.com/owncloud#- url: ..#g' $target_file 25 | 26 | # creating three caption groups 27 | # 1 ... - url: ../ 28 | # 2 ... docs-ocis 29 | # 3 ... .git 30 | # only taking 1 and 2 31 | # - url: ../docs-ocis.git --> - url: ../docs-ocis 32 | sed -i -r 's#(- url: \.\.\/)(.*)(.git)#\1\2#g' $target_file 33 | 34 | # Result 35 | echo "Done" 36 | echo 37 | -------------------------------------------------------------------------------- /book_templates/ownCloud_Admin_Manual.adoc: -------------------------------------------------------------------------------- 1 | = ownCloud Administration Manual 2 | :toc: 3 | :toclevels: 2 4 | :homepage: https://github.com/owncloud/docs 5 | :icon-set: octicon 6 | :icons: font 7 | :listing-caption: Listing 8 | :source-highlighter: rouge 9 | :version-label: Version: 10 | :module_base_path: modules/admin_manual/pages/ 11 | The ownCloud Team 12 | {revnumber}, {revdate} 13 | -------------------------------------------------------------------------------- /book_templates/ownCloud_Developer_Manual.adoc: -------------------------------------------------------------------------------- 1 | = ownCloud Developer Manual 2 | :toc: 3 | :toclevels: 2 4 | :homepage: https://github.com/owncloud/docs 5 | :icon-set: octicon 6 | :icons: font 7 | :listing-caption: Listing 8 | :source-highlighter: rouge 9 | :version-label: Version: 10 | :module_base_path: modules/developer_manual/pages/ 11 | The ownCloud Team 12 | {revnumber}, {revdate} 13 | -------------------------------------------------------------------------------- /book_templates/ownCloud_User_Manual.adoc: -------------------------------------------------------------------------------- 1 | = ownCloud User Manual 2 | :toc: 3 | :toclevels: 2 4 | :homepage: https://github.com/owncloud/docs 5 | :icon-set: octicon 6 | :icons: font 7 | :listing-caption: Listing 8 | :source-highlighter: rouge 9 | :version-label: Version: 10 | :module_base_path: modules/user_manual/pages/ 11 | The ownCloud Team 12 | {revnumber}, {revdate} 13 | -------------------------------------------------------------------------------- /docs/antora-site-structure.md: -------------------------------------------------------------------------------- 1 | # Antora Site Structure for Docs 2 | [link-asciidoc]: https://docs.asciidoctor.org/asciidoc/latest/ 3 | [link-antora]: https://antora.org 4 | [link-playbook]: https://docs.antora.org/antora/latest/playbook/ 5 | [link-ui]: https://docs.antora.org/antora-ui-default/ 6 | [link-resource-id]: https://docs.antora.org/antora/latest/page/resource-id-coordinates/ 7 | [link-standard-directories]: https://docs.antora.org/antora/latest/standard-directories/ 8 | [link-antora-yml]: https://docs.antora.org/antora/latest/component-version-descriptor/ 9 | [link-site-yml]: https://docs.antora.org/antora/latest/playbook/#whats-an-antora-playbook 10 | [custom-attrib-link]: https://docs.antora.org/antora/latest/page/attributes/#custom-attributes 11 | [antora-ui-link]: https://docs.antora.org/antora-ui-default/ 12 | [docs-ui-link]: https://github.com/owncloud/docs-ui 13 | 14 | **Table of Contents** 15 | 1. [Why Antora](#why-antora) 16 | 2. [Scope of Documentation Repositories](#scope-of-documentation-repositories) 17 | 3. [Scope of Content Accessibility](#scope-of-content-accessibility) 18 | 4. [Structure of Directories](#structure-of-directories) 19 | 5. [Scope of Antora Definitions](#scope-of-antora-definitions) 20 | 6. [The Antora UI Template](#the-antora-ui-template) 21 | 22 | ## Why Antora 23 | 24 | The main reasons for using [Antora][link-antora] are the following: 25 | 26 | 1. It uses and extends the [asciidoc][link-asciidoc] text writing format. 27 | * As an example, defining tables is so much easier in asciidoc compared to using markdown. 28 | * Using attributes (variables), which scope can be easily determined, content can be dynamically defined. 29 | 30 | 2. It extends asciidoc with [multi-repo][link-playbook] capabilities. This is done in a way where any issues identified can be easily tracked down to the source where this happens. 31 | 32 | 3. 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](https://docs.antora.org/antora/latest/page/resource-id-coordinates/). 33 | 34 | 4. You can easily extend functionalities with extensions added via `site.yml`. 35 | 36 | 5. Antora distincts writing the documentation and the [UI-Template][link-ui] defining how the content is presented. This is also done in a way where any change can be tracked down to its source. 37 | 38 | ## Scope of Documentation Repositories 39 | 40 | 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`. 41 | 42 | 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. 43 | 44 | Note that the `docs-main` repo only contains the entry page but no detailed product description. 45 | 46 | 47 | ``` 48 | repo content source 49 | 50 | docs --> docs-main 51 | docs-ocis 52 | docs-client-desktop 53 | docs-client-ios-app 54 | docs-client-android 55 | ... 56 | 57 | ``` 58 | 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. 59 | 60 | ### Scope of playbook files (site.yml) 61 | 62 | 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. 63 | 64 | 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! 65 | 66 | ### Scope of attributes (site.yml) 67 | 68 | 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. 69 | 70 | 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. 71 | 72 | ## Scope of Content Accessibility 73 | 74 | 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][link-resource-id] scheme. 75 | 76 | **IMPORTANT:**\ 77 | 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. 78 | 79 | Because of the setup we have made regarding testing, the direction of the arrow is important. 80 | 81 | 82 | **Possible** 83 | ``` 84 | docs --> docs-client-ios-app 85 | └> index.adoc 86 | ``` 87 | This 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. 88 | 89 | **Impossible** 90 | ``` 91 | docs-client-ios-app --> docs-client-desktop 92 | └> index.adoc 93 | 94 | docs-client-ios-app --> docs 95 | └> index.adoc 96 | 97 | ``` 98 | When 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. 99 | 100 | 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. 101 | 102 | ## Structure of Directories 103 | 104 | All doc repositories have an identical directory structure. This helps maintaining and accessing content easily. 105 | 106 | ### The Antora Directory Structure 107 | 108 | ``` 109 | modules/named-module-1/attachment 110 | /examples 111 | /images 112 | /pages 113 | /partials 114 | 115 | /named-module-2/attachments 116 | /... 117 | /... 118 | ``` 119 | 120 | Please see [Standard File and Directory Set][link-standard-directories] at `Example 1` for details. 121 | 122 | **Note that there is one important exception**: 123 | 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`. 124 | 125 | ### Other Necessary Directories 126 | 127 | Beside the necessary directories for node, other important directories are: 128 | ``` 129 | bin/ Helper scripts to maintain the documentation 130 | book_templates/ Template file(s) to create the pdf file 131 | ext-antora/ Antora extensions necessary for the build process 132 | ext-asciidoc/ Asciidoc extensions necessary for the build process 133 | pdf_web/ Output directory of generated pdf files, currently unused! 134 | public/ Output directory of generated html files, only used locally! 135 | resources/ Themes necessary for creating pdf files, currently unused! 136 | tmp/ Temp directory used for htmltest (broken link checking) 137 | ``` 138 | ### Important Files 139 | 140 | The following files are important to run a build properly.\ 141 | Note that Node related stuff is not mentioned explicitly: 142 | 143 | ``` 144 | .drone.star Define the build process steps when triggered by a PR 145 | package.json Define the antora environment and scripts to run at the cli 146 | antora.yml Contains definitions and attributes that only belong 147 | to the respective component (version dependent!) 148 | site.yml Global site definitions, attributes defined overwrite global ones 149 | global-attributes.yml The file containing global attributes used by the extension. 150 | Mandatory for the docs repo, optional otherwise (version dependent!) 151 | ``` 152 | 153 | ## Scope of Antora Definitions 154 | 155 | ### Versioning 156 | 157 | While you can read more details about [What is antora.yml?][link-antora-yml] and [What is site.yml (the playbook)][link-site-yml], here are some important items: 158 | 159 | 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. 160 | 161 | ### Accessibility and Availability of Attributes 162 | 163 | 1. The scope of attributes defined in a page is limited to that page only. 164 | 2. The scope of attributes defined in `antora.yml` is limited to the branch and component where it is defined. This is also true for attributes that should be accessed from the UI-Template. 165 | 3. The scope of attributes defined in `site.yml` including defined via the `global-attributes.yml` file are _global_. The term global has two flavours in our setup: 166 | 1. When used in the building repo `docs`, it becomes available to all sources at any time. 167 | 2. When used in a content source, it is only availabe to the content source during a local test build. 168 | 4. 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 use `page.attribute.name` where `name` is without leading `page-` For details see [AsciiDoc Attributes in Antora][custom-attrib-link]. 169 | 170 | **IMPORTANT** 171 | 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. 172 | 173 | ## The Antora UI Template 174 | 175 | As described on top, Antora separates the writing of text and the [presentation design][antora-ui-link]. Our presentation design is defined in the [docs-ui][docs-ui-link] repository. Any change made in the UI affects the complete documentation, careful tests are mandatory. 176 | -------------------------------------------------------------------------------- /docs/checking-broken-links.md: -------------------------------------------------------------------------------- 1 | # Checking Broken Links 2 | 3 | ## Introduction 4 | 5 | Checking for broken links is a science on its own. External webpages, internal sites and 6 | references to anchors can cause broken links in various ways. While it looks relatively 7 | easy to check for broken anchors, not many free tools provide this functionality. 8 | Various tools behave and report access to links in different ways. Configuration, like the 9 | possibility to define patterns in an elegant way to exclude link searches, is also a rare feature. 10 | There is no free one-fits-all tool which means you may have to use more than one tool to 11 | differentiate real broken links from false positives or to get results the other tools may not provide. 12 | 13 | ## Preparation 14 | 15 | To check broken links, you need to prepare with the following steps: 16 | 17 | 1. Make the compiled documentation available for browsing by using a webserver like 18 | [our npm target](./build-the-docs.md#viewing-the-html-documentation), [PHP's built-in webserver](https://secure.php.net/manual/en/features.commandline.webserver.php), Apache or NGINX 19 | 2. Build the local docs with ``npm antora --url http://localhost:8080`` 20 | 3. Use an already provided or install a Broken Link Checker 21 | 22 | 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`. 23 | 24 | **Note** You may get false positives because of sample links or addresses pointing to nowhere. This is normal and not a broken link. 25 | 26 | **Note** It is good to pipe the output of the results to a file for easy checking. 27 | 28 | ## Link Checkers provided by the Documentation 29 | ### Antora xref-validator 30 | 31 | The Antora ``xref-validator`` provided by the Antora core team, is able to check the [native Antora xref links](https://docs.antora.org/antora/1.0/asciidoc/page-to-page-xref/#xref-and-page-id-anatomy). 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. 32 | 33 | ### Using npm Validate 34 | 35 | This is the easiest way and uses the ``xref-validator`` to validate the documentation, using predefined settings. 36 | 37 | ```console 38 | npm validate 39 | ``` 40 | 41 | ### Using the Validator with Own Settings 42 | 43 | If you want to use your own settings, run the command passing the necessary parameters manually, as in the example below. 44 | 45 | ```console 46 | antora generate \ 47 | --generator=./generators/xref-validator.js \ 48 | site.yml 49 | ``` 50 | 51 | #### Example Output 52 | 53 | 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: 54 | 55 | ```console 56 | worktree: /var/www/owncloud/docs | component: server | version: master 57 | path: modules/admin_manual/nav.adoc | xref: configuration/server/security/password-policy.adoc 58 | path: modules/admin_manual/pages/configuration/files/external_storage/configuration.adoc | xref: server/import_ssl_cert.adoc 59 | path: modules/admin_manual/pages/configuration/files/file_sharing_configuration.adoc | xref: server/configuration/server/security/password_policy.adoc 60 | ``` 61 | 62 | ### npm Linkcheck 63 | 64 | If you installed the Antora dependencies via `npm install`, then a broken link checker is available. To run it, you must have one terminal open and run `npm serve` to start a http server and in another terminal using the following command: 65 | 66 | ```console 67 | npm linkcheck http://localhost:8080/server/next | grep "BROKEN" 68 | ``` 69 | 70 | #### Example Output 71 | 72 | ```console 73 | ... 74 | ├─BROKEN─ http://mechanics.flite.com/blog/2014/07/29/using-innodb-large-prefix-to-avoid-error-1071/ (BLC_UNKNOWN) 75 | ├─BROKEN─ http://bucket.hostname.domain/ (ERRNO_ENOTFOUND) 76 | ├─BROKEN─ http://hostname.domain/bucket (ERRNO_ENOTFOUND) 77 | ├─BROKEN─ https://example.com/owncloud (HTTP_404) 78 | ├─BROKEN─ https://example.com/owncloud (HTTP_404) 79 | ... 80 | ``` 81 | Note: in the example output above, only the first entry is a genuine broken link. 82 | All the others in the list are example links, and therefore not broken. 83 | 84 | ## Publicly Available Linkcheckers 85 | 86 | ### htmltest by Will Pimblett 87 | 88 | This is an extremely fast and very comfortable / configurable link checker written in go. 89 | 90 | A description of ``htmltest`` can be found [here](https://github.com/wjdp/htmltest). 91 | Follow [this](https://dart.dev/get-dart) procedure, to install ``dart`` and 92 | [this](https://github.com/wjdp/htmltest#floppy_disk-installation) link to install ``htmltest``. 93 | A [System-wide Install](https://github.com/wjdp/htmltest#system-wide-install) is recommended. 94 | 95 | To check docs, you first need to build the actual docs running ``npm antora-local``. This creates all necessary files in the ``public`` directory. 96 | 97 | 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. 98 | 99 | 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. 100 | 101 | 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. 102 | 103 | Note, run ``htmltest public`` which includes checking external links from the master branch to avoid antora build artifacts linking to the branch name. 104 | 105 | #### Example Output 106 | 107 | ``` 108 | server/10.8/admin_manual/maintenance/export_import_instance_data.html 109 | hash does not exist --- server/10.8/admin_manual/maintenance/export_import_instance_data.html --> #what_is_exported 110 | hash does not exist --- server/10.8/admin_manual/maintenance/export_import_instance_data.html --> #known_limitations 111 | hash does not exist --- server/10.8/admin_manual/maintenance/export_import_instance_data.html --> ../configuration/server/occ_command.html#data_exporter 112 | hash does not exist --- server/10.8/admin_manual/maintenance/export_import_instance_data.html --> #known_limitations 113 | ``` 114 | 115 | As 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` 116 | 117 | 118 | ### Linkcheck by Filip Hracek 119 | 120 | This is an extremely fast and very comfortable / configurable link checker written in go. 121 | 122 | A description of ``linkcheck`` can be found [here](https://github.com/filiph/linkcheck#linkcheck). 123 | Follow [this](https://github.com/filiph/linkcheck#step-1-install-dart) procedure, 124 | to install or update ``linkcheck``, which needs ``dart``: 125 | 126 | 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: 127 | 128 | Because ``linkcheck`` provides the possibility to use a file to exclude search patterns, 129 | it is good advice to create a file with the following predefined content. In this example, 130 | the file is named ``my_skip_file.txt`` and saved one level below the local docs repository. 131 | Adapt the content to your needs. 132 | 133 | ```console 134 | # exclude check to particular sub-pages of owncloud.com 135 | https://owncloud.com/news 136 | https://owncloud.com/support 137 | https://owncloud.com/install 138 | 139 | # because of denied by robots.txt 140 | https://github.com 141 | https://gist.github.com 142 | https://www.samba.org 143 | https://linux.die.net 144 | https://mycloud.org 145 | https://www.google.de 146 | https://www.tscp.org 147 | 148 | # known false positives 149 | https://www.cyberciti.biz/faq/upgrade-ubuntu-18-04-to-20-04-lts-using-command-line/ 150 | https://www.technetexperts.com/mobile/creating-static-library-in-ios-app-development/ 151 | 152 | # no missing favicons when localhost 153 | http://localhost:8080/manifest.json 154 | http://localhost:8080/apple-touch-icon.png 155 | http://localhost:8080/favicon.svg 156 | http://localhost:8080/favicon-32x32.png 157 | http://localhost:8080/favicon-16x16.png 158 | http://localhost:8080/safari-pinned-tab.svg 159 | 160 | # example links like: https:/// or https://{{.preferred_username}} 161 | # or image generation (kroki) 162 | https://%3C 163 | https://%7B%7B 164 | https://www.example.com 165 | https://kroki.io 166 | ``` 167 | 168 | It is good practice to first start checking excluding external pages / sites. 169 | ``linkcheck`` will report internal broken links AND broken links to anchors. 170 | Note: you can pipe the result into a file. Just add in ``> ../linkcheck.log``. 171 | The grep filter reduces the output to important ones. 172 | 173 | ```console 174 | linkcheck --skip-file ../my_skip_file.txt --no-connection-failures-as-warnings | grep "HTTP 40" 175 | ``` 176 | 177 | Fix any broken internal links found reported. 178 | 179 | Continue with checking also external pages / sites: 180 | 181 | ```console 182 | linkcheck -e --skip-file ../my_skip_file.txt --no-connection-failures-as-warnings | grep "HTTP 40" 183 | ``` 184 | 185 | #### Example Output 186 | 187 | ``` 188 | No URL given, checking http://localhost:8080/ 189 | Crawling... 190 | 191 | http://localhost:8080/server/admin_manual/appliance/wnd_setup.html 192 | - (1297:3) 'Windows ..' => http://localhost:8080/server/admin_manual/enterprise/external_storage/windows-network-drive_configuration.html#wnd-listen (HTTP 200 but missing anchor) 193 | 194 | ... 195 | 196 | http://localhost:8080/server/admin_manual/configuration/database/linux_database_configuration.html 197 | - (1451:3) 'https://..' => https://mariadb.com/kb/en/mariadb/xtradbinnodb-server-system-variables/%5C#innodb_large_prefix (connection failed) 198 | - (1457:3) 'http://m..' => http://mechanics.flite.com/blog/2014/07/29/using-innodb-large-prefix-to-avoid-error-1071/ (connection failed) 199 | ``` 200 | 201 | In the example output above, the first entry ``HTTP 200 but missing anchor`` highlights a broken link to an anchor. 202 | The second entry ``connection failed`` highlights the possibility that the page may no longer be accessible. 203 | You have to manually check if it is a false-positive or not. 204 | -------------------------------------------------------------------------------- /docs/doc-guidelines.md: -------------------------------------------------------------------------------- 1 | # Documentation Guidelines 2 | 3 | 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. 4 | 5 | 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. 6 | 7 | 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/. 8 | 9 | If you're new to writing or editing ownCloud documentation, we recommend the [Getting Started Guide](https://github.com/owncloud/docs/blob/master/docs/getting-started.md) and [Building the Documentation](https://github.com/owncloud/docs/blob/master/docs/build-the-docs.md) to get a good understanding of what awaits you. (Just don't let it discourage you!). Keep the [Best Practices Guide](https://github.com/owncloud/docs/blob/master/docs/best-practices.md) collection in mind. 10 | 11 | To contribute to the documentation by providing content or fixing issues in the existing documentation: 12 | 13 | - Clone the respective repository. 14 | - Create a local branch. 15 | - Edit an existing file or add a new one. 16 | 17 | Before pushing the file to Github, please take care of the following: 18 | 19 | 1. 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 `@mmattel` or `@phil-davis` when you create a pull request on Github. 20 | 2. While writing or editing, please follow the [Style Guide](https://github.com/owncloud/docs/blob/master/docs/style-guide.md). 21 | 3. [Build the documentation](https://github.com/owncloud/docs/blob/master/docs/build-the-docs.md) and check the layout. 22 | 23 | Commit all changed files and push the branch to GitHub.\ 24 | 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: 25 | 26 | 1. **4 Eyes Principle (4EP)** 27 | 28 | 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`. 29 | 30 | Exceptions to the 4EP must be documented in the PR description and can be made if: 31 | 32 | 1. Language violations require immediate action, 33 | 2. The docs web site is not usable, partially or in full, without an emergency docs PR. 34 | 35 | 2. **Security and Dependency Bumps** 36 | 37 | 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 `@mmattel` or `@phil-davis` as reviewer. 38 | 39 | 3. **The main branch for changes is `master`**\ 40 | Any changes start there. Exception:\ 41 | Changes only apply to the branch the PR is made for, mandatory add a comment note. 42 | 43 | 4. **Technical and Process Changes** 44 | 45 | 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. 46 | 47 | 5. **The PR title should summarize what the changes are about** 48 | 49 | 6. **Provide in the PR description the following information**\ 50 | This gives reviewers a quick but thorough understanding of what they should be looking for. 51 | 52 | 1. What changes or additions you made 53 | 2. The positive impact of these changes if they aren't glaringly obvious 54 | 3. Special notes like the wish for language proofing 55 | 4. To which branches the PR needs to get backported (usually to the current release and the previous one for corrections to existing documentation) 56 | 5. A link to the docs issue if one exists 57 | 6. A link to the issue/PR in the corresponding repo this change will fix. 58 | 59 | 7. **Backporting** 60 | 61 | 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: 62 | 63 | 1. [target branch] [source PR number] original headline\ 64 | Example: `[10.15] [3456] Fix missing php library` 65 | 66 | 2. As comment use `Backport of #3456` where 3456 is the source PR number.\ 67 | This links the backport to the source PR. Set the label `backport`. 68 | 69 | 3. The 4EP applies. 70 | 71 | 8. **Predefined Global Attributes** 72 | 73 | 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](https://github.com/owncloud/docs/blob/master/docs/best-practices.md#attributes) in the docs repo for more information on how to do that. 74 | 75 | 9. **Support Community Contributors** 76 | 77 | 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. 78 | -------------------------------------------------------------------------------- /docs/extensions.md: -------------------------------------------------------------------------------- 1 | # Extensions 2 | 3 | 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](https://github.com/mmattel/Antora-Asciidoc-Extensions) repository for more details. 4 | 5 | ## Mandatory Extensions 6 | 7 | **Asciidoc** 8 | 9 | * Add Tab Sets: `./ext-asciidoc/tabs.js` 10 | * Include Content via URL: `./ext-asciidoc/remote-include-processor.js` 11 | * Convert diagrams to images: `asciidoctor-kroki # integrated via npm` 12 | 13 | **Antora** 14 | 15 | * Create an Elastic Search Index: `./ext-antora/generate-index.js` 16 | * Load Global Site Attributes: `./ext-antora/load-global-site-attributes.js` 17 | 18 | ## Optional Extensions 19 | 20 | **Antora** 21 | 22 | * Print Component Version File Table: `./ext-antora/comp-version.js` 23 | * Print Attributes Used in Playbook: `./ext-antora/attributes-used-in-site-yml.js` 24 | * Print Attributes Used in Component Descriptor: `./ext-antora/attributes-used-in-antora-yml.js` 25 | 26 | ## UI 27 | 28 | Though not an Antora/Asciidoc extension, but required for presenting images: 29 | 30 | **docs-ui** 31 | 32 | * Medium-Zoom 33 | -------------------------------------------------------------------------------- /docs/getting-started.md: -------------------------------------------------------------------------------- 1 | # Getting Started 2 | 3 | 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. 4 | 5 | ## For Non-Developers 6 | 7 | Even if you’re not a developer, you can contribute to the ownCloud documentation by [creating new issues](#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](https://www.google.com/chrome/index.html), [Mozilla Firefox](https://www.mozilla.org/en-US/firefox/new/), [Apple Safari](https://www.apple.com/safari/), or [Microsoft Edge](https://www.microsoft.com/en-us/windows/microsoft-edge). 8 | 9 | **NOTE:** Most browsers support [live preview](#environmental-setups-depending-the-kind-of-changes). 10 | 11 | ### Initial Steps 12 | 13 | Before you can contribute to the documentation, you need to: 14 | 15 | 1. [Have a GitHub account](#have-a-github-account). 16 | 2. [Know the AsciiDoc basics.](#asciidoc-basics) 17 | 18 | #### Have a GitHub Account 19 | 20 | If you don't already have an account, you can [sign up for a new one](https://github.com/). You only need to provide a _username_, _email address_, and a _password_. 21 | 22 | ![Create a new GitHub account.](images/getting-started/non-developers/github-signup.png) 23 | 24 | #### Know the AsciiDoc Basics 25 | 26 | While [the AsciiDoc file format](https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/) 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_. 27 | 28 | ```asciidoc 29 | = Top-Level Header 30 | 31 | An introduction to http://asciidoc.org[AsciiDoc]. 32 | 33 | == Second-Level Header 34 | 35 | * item 1 36 | * item 2 37 | 38 | [source,ruby] 39 | ==== 40 | puts "Hello, World!" 41 | ==== 42 | ``` 43 | 44 | Have a read through [the AsciiDoctor Syntax Quick Reference](https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/) to familiarise yourself with the format's essentials. Please also refer to [Best Practices and Tips](./best-practices.md) for more information. 45 | 46 | #### Creating New Issues 47 | 48 | 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: 49 | 50 | - Information is missing, incorrect, or outdated; or 51 | - A new feature has been created that needs to be documented. 52 | 53 | 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. 54 | 55 | ![Create a new issue.](images/getting-started/non-developers/create-new-issue.png) 56 | 57 | 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. 58 | 59 | 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. 60 | 61 | Four sections should be filled out (the more, the better): 62 | 63 | 1. What type of content change is this? 64 | 2. Which Manual Does This Relate to? 65 | 3. What Needs to be Documented? 66 | 4. Why Should This Change Be Made? 67 | 68 | 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. 69 | 70 | *Note:* The description text can be, if desired, formatted with [Markdown](https://guides.github.com/features/mastering-markdown/), which is a simple way of formatting text, to give it more significant meaning. 71 | 72 | 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. 73 | 74 | ![Assign a GitHub Issue.](images/getting-started/non-developers/assign-issue.png) 75 | 76 | 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. 77 | 78 | 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. 79 | 80 | 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. 81 | 82 | ![Current Issues.](images/getting-started/non-developers/current-docs-issues.png) 83 | 84 | ## For Developers 85 | 86 | ### Initial Steps 87 | 88 | To contribute to the documentation, you need to: 89 | 90 | 1. Learn [Antora's basics](./what-is-antora.md). 91 | 2. Learn [the AsciiDoc basics](./what-is-asciidoc.md). 92 | In addition, check out the Asciidoctor [Writers Guide](https://asciidoctor.org/docs/asciidoc-writers-guide/), [User Manual](https://asciidoctor.org/docs/user-manual/), and [Syntax Quick Reference](https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/). 93 | 3. Make sure you have [tools](./what-is-asciidoc.md#writing--editing-asciidoc-files) that can edit and preview AsciiDoc files. 94 | 4. Setup a [GitHub account](https://github.com/), if you haven't already. 95 | 5. Setup your local copy of the docs repository 96 | 6. Environmental setups depending on the kind of changes 97 | 7. Contributing to the documentation 98 | 8. Getting support 99 | 100 | ### Setup Your Local Copy of the Docs Repository 101 | 102 | With this done, you then need to get your local copy of the docs repository ready. To do this, follow these three steps. 103 | 104 | 1. Fork [the docs repository](https://github.com/owncloud/docs/). 105 | This is necessary, as you won't be able to push changes directly to the docs repository. 106 | 107 | 2. Clone the docs repository locally and enter it. 108 | 109 | ```console 110 | git clone git@github.com:owncloud/docs.git 111 | cd docs 112 | ``` 113 | 114 | 3. Add a remote to your fork, by substituting your GitHub username in the command below. 115 | 116 | ```console 117 | git remote add {username} git@github.com:{username}/docs.git 118 | git fetch {username} 119 | ``` 120 | 121 | ### Environmental Setups Depending on the Kind of Changes 122 | 123 | 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. 124 | 125 | #### You Are Making Text Changes Only 126 | 127 | If you're making text changes only, we recommend installing the AsciiDoc Live Preview plugin(s): 128 | 129 | 1. To your browser: 130 | - Firefox: [asciidoctorjs-live preview](https://addons.mozilla.org/en-US/firefox/addon/asciidoctorjs-live-preview) 131 | - Other [browser](https://asciidoctor.org/docs/editing-asciidoc-with-live-preview/) (The supported browsers are: *FireFox*, *Google Chrome*, or *Opera*, -- if *FireFox* installation fails, try the above instead). 132 | 2. To your [text editor or IDE](https://asciidoctor.org/docs/editing-asciidoc-with-live-preview/#using-a-modern-text-editoride), *if it has one*. 133 | 134 | 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. 135 | 136 | **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. 137 | 138 | #### You Are Working With Inline Code Examples, Images, and Attachments 139 | 140 | 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](./install-antora.md). 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. 141 | 142 | 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. 143 | 144 | Next, you need to learn how to [build the docs](./build-the-docs.md) from the command line and how to review the changes in your browser. 145 | 146 | #### Broken Link Checker 147 | 148 | To check for broken links manually, see [install and use a broken-link-checker](./checking-broken-links.md). 149 | 150 | ### Contributing to the Documentation 151 | 152 | 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. 153 | 154 | 1. Create a local development branch off of `master` or another development branch and switch to it. 155 | You can do this in one command: `git checkout -b {branch-name}`. 156 | We recommend naming the branch such that you'll recognize its purpose; e.g., `deprecate-some-occ-command`, `document-firebase-database-support`. 157 | 2. Do some work, commit, repeat as necessary. 158 | 3. Push the branch to your remote fork of the docs repository. 159 | 4. Send a pull request from your fork to the docs repository. 160 | 161 | Here's an example of contributing to the documentation 162 | 163 | ```console 164 | $ git checkout -b deprecate-some-occ-command 165 | Switched to a new branch 'deprecate-some-occ-command' 166 | 167 | ... do some work ... 168 | 169 | $ git commit 170 | ... write your log message ... 171 | 172 | $ git push {username} deprecate-some-occ-command:deprecate-some-occ-command 173 | Counting objects: 38, done. 174 | Delta compression using up to 2 threads. 175 | Compression objects: 100% (18/18), done. 176 | Writing objects: 100% (20/20), 8.19KiB, done. 177 | Total 20 (delta 12), reused 0 (delta 0) 178 | To ssh://git@github.com/{username}/docs.git 179 | b5583aa..4f51698 HEAD -> master 180 | ``` 181 | 182 | #### Cleaning Up Your Branches After They're Merged 183 | 184 | 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. 185 | 186 | ##### Local Branch Cleanup 187 | 188 | ```console 189 | $ git branch -d 190 | ``` 191 | 192 | ##### Remote Branch Removal 193 | 194 | ```console 195 | $ git push {username} : 196 | ``` 197 | 198 | **Note:** you can also delete a remote branch through the GitHub UI. 199 | 200 | ## The Branching Workflow 201 | 202 | The branching workflow is only necessary for versioned repos (documentations). Please refer to the [branching workflow](./the-branching-workflow.md) to learn about how git branches are used to manage and build the documentation. 203 | 204 | ## Backporting 205 | 206 | If you want or need to backport a merged PR, you can easily do that by using the linked [backport](../bin/git_commands/backport.sh) 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. 207 | 208 | Note that it may occur that you have conflicts, resolve them first with standard git methods to proceed. 209 | 210 | 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. 211 | 212 | If you want to make this script part of the git command set, create a git alias: 213 | 214 | Open the `~/.gitconfig` file with the editor of your choice and add the following: 215 | 216 | ``` 217 | [alias] 218 | backport = !bash -c '/backport.sh $1 $2' - 219 | ``` 220 | 221 | You can now create a backport by invoking the following command: 222 | 223 | ``` 224 | git backport 225 | ``` 226 | 227 | 228 | ## Build Pipeline and Web Deployment 229 | 230 | Please refer to the [documentation build pipeline](./the-build-pipeline.md) to learn about how the documentation is built and deployed to production. 231 | 232 | ## Getting Support 233 | 234 | If you need any support when making changes to the documentation, you can always get it in the `#documentation` channel in https://talk.owncloud.com. We're there to help you. 235 | -------------------------------------------------------------------------------- /docs/html-to-pdf.md: -------------------------------------------------------------------------------- 1 | # HTML to PDF 2 | 3 | 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. 4 | 5 | ## How to Use 6 | 7 | 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. 8 | 9 | ```bash 10 | python bin/ownCloudDocPdf.py [URL] 11 | ``` 12 | 13 | ## Example 14 | 15 | ```python 16 | python bin/ownCloudDocPdf.py https://doc.owncloud.com/webui/next/classic_ui/ 17 | ``` 18 | 19 | ## Dependencies 20 | 21 | - `Python (Script developed and tested with version 3.10)` 22 | - `wkhtmltopdf` 23 | - `pdftk` 24 | - `requests` 25 | 26 | ## Installing Dependencies 27 | 28 | Install the Python requests library: 29 | 30 | ```bash 31 | python -m pip install requests 32 | ``` 33 | On Debian-based systems, install `wkhtmltopdf` and `pdftk` using: 34 | 35 | ```bash 36 | sudo apt-get install wkhtmltopdf pdftk 37 | ``` 38 | On other systems, please refer to the documentation for `wkhtmltopdf` and `pdftk` for installation instructions. 39 | 40 | **Output** 41 | 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.). 42 | 43 | **Notes** 44 | The temporary PDF files generated for each page are stored under /tmp/ and are deleted after the final PDF is merged. 45 | 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. 46 | 47 | -------------------------------------------------------------------------------- /docs/images/antora-ui-anotated.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/owncloud/docs/08c13d3e438dbe6bd06b7ebab9dd6f215ed41719/docs/images/antora-ui-anotated.png -------------------------------------------------------------------------------- /docs/images/antora-version-navigation.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/owncloud/docs/08c13d3e438dbe6bd06b7ebab9dd6f215ed41719/docs/images/antora-version-navigation.png -------------------------------------------------------------------------------- /docs/images/asciidoc-syntax-quick-reference.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/owncloud/docs/08c13d3e438dbe6bd06b7ebab9dd6f215ed41719/docs/images/asciidoc-syntax-quick-reference.png -------------------------------------------------------------------------------- /docs/images/editing-asciidoc-in-atom.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/owncloud/docs/08c13d3e438dbe6bd06b7ebab9dd6f215ed41719/docs/images/editing-asciidoc-in-atom.png -------------------------------------------------------------------------------- /docs/images/editing-asciidoc-in-phpstorm.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/owncloud/docs/08c13d3e438dbe6bd06b7ebab9dd6f215ed41719/docs/images/editing-asciidoc-in-phpstorm.png -------------------------------------------------------------------------------- /docs/images/editing-asciidoc-in-sublime-text.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/owncloud/docs/08c13d3e438dbe6bd06b7ebab9dd6f215ed41719/docs/images/editing-asciidoc-in-sublime-text.png -------------------------------------------------------------------------------- /docs/images/editing-asciidoc-in-vim.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/owncloud/docs/08c13d3e438dbe6bd06b7ebab9dd6f215ed41719/docs/images/editing-asciidoc-in-vim.png -------------------------------------------------------------------------------- /docs/images/editing-asciidoc-in-vscode.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/owncloud/docs/08c13d3e438dbe6bd06b7ebab9dd6f215ed41719/docs/images/editing-asciidoc-in-vscode.png -------------------------------------------------------------------------------- /docs/images/getting-started/non-developers/add-comment-to-issue.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/owncloud/docs/08c13d3e438dbe6bd06b7ebab9dd6f215ed41719/docs/images/getting-started/non-developers/add-comment-to-issue.png -------------------------------------------------------------------------------- /docs/images/getting-started/non-developers/assign-issue.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/owncloud/docs/08c13d3e438dbe6bd06b7ebab9dd6f215ed41719/docs/images/getting-started/non-developers/assign-issue.png -------------------------------------------------------------------------------- /docs/images/getting-started/non-developers/commit-change-to-docs-directly-on-github.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/owncloud/docs/08c13d3e438dbe6bd06b7ebab9dd6f215ed41719/docs/images/getting-started/non-developers/commit-change-to-docs-directly-on-github.png -------------------------------------------------------------------------------- /docs/images/getting-started/non-developers/create-new-issue.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/owncloud/docs/08c13d3e438dbe6bd06b7ebab9dd6f215ed41719/docs/images/getting-started/non-developers/create-new-issue.png -------------------------------------------------------------------------------- /docs/images/getting-started/non-developers/current-docs-issues.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/owncloud/docs/08c13d3e438dbe6bd06b7ebab9dd6f215ed41719/docs/images/getting-started/non-developers/current-docs-issues.png -------------------------------------------------------------------------------- /docs/images/getting-started/non-developers/docs-home-edit-this-page.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/owncloud/docs/08c13d3e438dbe6bd06b7ebab9dd6f215ed41719/docs/images/getting-started/non-developers/docs-home-edit-this-page.png -------------------------------------------------------------------------------- /docs/images/getting-started/non-developers/docs-repo-home.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/owncloud/docs/08c13d3e438dbe6bd06b7ebab9dd6f215ed41719/docs/images/getting-started/non-developers/docs-repo-home.png -------------------------------------------------------------------------------- /docs/images/getting-started/non-developers/edit-page-on-github-directly.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/owncloud/docs/08c13d3e438dbe6bd06b7ebab9dd6f215ed41719/docs/images/getting-started/non-developers/edit-page-on-github-directly.png -------------------------------------------------------------------------------- /docs/images/getting-started/non-developers/github-signup.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/owncloud/docs/08c13d3e438dbe6bd06b7ebab9dd6f215ed41719/docs/images/getting-started/non-developers/github-signup.png -------------------------------------------------------------------------------- /docs/images/getting-started/non-developers/new-docs-issue.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/owncloud/docs/08c13d3e438dbe6bd06b7ebab9dd6f215ed41719/docs/images/getting-started/non-developers/new-docs-issue.png -------------------------------------------------------------------------------- /docs/images/the-branching-workflow.key: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/owncloud/docs/08c13d3e438dbe6bd06b7ebab9dd6f215ed41719/docs/images/the-branching-workflow.key -------------------------------------------------------------------------------- /docs/images/the-branching-workflow.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/owncloud/docs/08c13d3e438dbe6bd06b7ebab9dd6f215ed41719/docs/images/the-branching-workflow.png -------------------------------------------------------------------------------- /docs/images/viewing-asciidoc-in-firefox-with-the-asciidoc-live-preview-plugin.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/owncloud/docs/08c13d3e438dbe6bd06b7ebab9dd6f215ed41719/docs/images/viewing-asciidoc-in-firefox-with-the-asciidoc-live-preview-plugin.png -------------------------------------------------------------------------------- /docs/images/viewing-the-locally-generated-antora-documentation.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/owncloud/docs/08c13d3e438dbe6bd06b7ebab9dd6f215ed41719/docs/images/viewing-the-locally-generated-antora-documentation.png -------------------------------------------------------------------------------- /docs/images/what-is-antora/the-antora-version-changer.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/owncloud/docs/08c13d3e438dbe6bd06b7ebab9dd6f215ed41719/docs/images/what-is-antora/the-antora-version-changer.gif -------------------------------------------------------------------------------- /docs/images/what-is-asciidoc/setting-imagesdir-in-atom.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/owncloud/docs/08c13d3e438dbe6bd06b7ebab9dd6f215ed41719/docs/images/what-is-asciidoc/setting-imagesdir-in-atom.png -------------------------------------------------------------------------------- /docs/images/what-is-asciidoc/setting-imagesdir-in-intellij.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/owncloud/docs/08c13d3e438dbe6bd06b7ebab9dd6f215ed41719/docs/images/what-is-asciidoc/setting-imagesdir-in-intellij.png -------------------------------------------------------------------------------- /docs/install-antora.md: -------------------------------------------------------------------------------- 1 | # Install Antora 2 | 3 | Installing Antora on your local development (virtual) machine doesn't take *too* much time, based on whether you install the tools directly. 4 | 5 | **Please note:** if you just want to make text changes, then installing the [AsciiDoc Live Preview Plugin](https://asciidoctor.org/docs/editing-asciidoc-with-live-preview/), whether as a Browser plugin, or as part of your text editor or IDE, may be sufficient for your needs. 6 | 7 | ## Install The Antora Tools Locally 8 | 9 | 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](https://docs.antora.org/antora/latest/install/install-antora/). Note, if possible, aviod using Windows as it more and more conflicts with extensions and tools. 10 | 11 | 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. 12 | 13 | With the dependencies and Antora tools installed, you’re ready to [build the documentation](./build-the-docs.md) locally. 14 | -------------------------------------------------------------------------------- /docs/new-version-branch.md: -------------------------------------------------------------------------------- 1 | # Create a New Version Branch for Docs 2 | 3 | In general, the docs branch itself does not have versioning, but some doc repos have. If a doc repo has versioning, it impacts of course this repo but usually only in the way to set version attribute values correctly. For details see the corresponding **Create a New Version Branch** document of the sourcing doc repo. 4 | -------------------------------------------------------------------------------- /docs/style-guide.md: -------------------------------------------------------------------------------- 1 | # Style Guide 2 | 3 | With regard to English, many things are optional, and style certainly is subjective. This style guide should help all contributors write professionally and consistently. This is a work in progress and will be adjusted as questions arise or suggestions are made. 4 | 5 | 6 | ## Basic Writing Rules 7 | 8 | - American English is used for all ownCloud documentation, therefore use customize instead of customise, behavior instead of behaviour, etc. 9 | 10 | - Use gender neutral language, which means don't use "he" and "his" as pronouns for an individual user. Where possible, use the plural instead. Most statements refer to users and their files. When writing about an individual user like admin, either use the awkwardly ungrammatical but legit "they" even with a singular noun or use "she or he" and "he or she" alternately. 11 | 12 | - Only use 'please' if you are asking a favor of the reader like sending feedback or reporting issues. No need to beg the reader to do something that is necessary to achieve a certain goal. 13 | 14 | - Contractions as in "don't" are okay to use. 15 | 16 | - Avoid writing "in order to" because "to" says it all. 17 | 18 | ## Use of Lower and Upper Case Letters: 19 | 20 | - For headlines, we adhere to the rules of the Chicago Manual of Style. When unsure, use the following tool and select "Do Not Capitalize Words Based on Length": 21 | https://headlinecapitalization.com/ 22 | 23 | - When referring to a figure or table in the surrounding text, capitalize Figure 2 or Table 1. 24 | 25 | 26 | ## Punctuation: 27 | 28 | Some basic punctuation rules in English: 29 | 30 | - If a sentence starts with a subordinate clause (like this one does), a comma needs to be set before the main clause starts. Just like in German. 31 | 32 | - A main clause (like this one) is followed by a subordinate clause without a comma although in German a comma would be set before the 'although' in this sentence. Simple examples: 33 | 34 | When yada happens, you need to use a comma. 35 | 36 | Use no comma if dada happens. 37 | 38 | - We don't use serial (Oxford) commas in a series of three and more. They are fancy but serve no purpose. Here are examples of serial commas we do NOT want to use, thus placed in []: 39 | 40 | Click on the icon, select the desired item from the drop-down menu[,] and click on it. 41 | 42 | The icons, the menu[,] and the tool bar are three navigation elements, but don't need a comma before "and". 43 | 44 | - As a rule of thumb: you don't need commas before "and", except in rare cases when two main clauses are connected by "and": The banana icon is yellow, and the cucumber icon is green. Other coordinating conjunctions are 'but, or, so, yet'. 45 | 46 | If you wonder whether commas are really that important, they can actually change the meaning of a sentence if only in rare cases. Look at the following example with and without the second comma: 47 | 48 | A panda enters a bar, eats[,] shoots and leaves. 49 | 50 | The comma decides whether the panda eats bamboo shoots or shoots firearms. 51 | 52 | 53 | ## Hyphenated Words 54 | 55 | In English, composite terms are rarely hyphenated except for adjectives. 56 | Some nouns have become one word over time: 57 | 58 | username 59 | 60 | cellphone 61 | 62 | ... 63 | 64 | However, host name is still two words. 65 | 66 | - Never use drop-down-menu or pop-up-window, instead it's drop-down menu and pop-up window. 67 | 68 | - Using a hyphen is the regular spelling for composite adjectives: right-hand side, four-year-old computer. 69 | 70 | ## Acronyms: 71 | 72 | At first mention, use the full term with the acronym in parenthesis. Some examples: ownCloud Infinite Scale (oCIS) or Internet Content Adaptation Protocol (ICAP). Afterward you can simply use oCIS and ICAP. This rule can be neglected with widely known acronyms like IBM, AMD, etc. 73 | 74 | ## List of words often spelled wrong: 75 | 76 | email (not e-mail) 77 | 78 | [to be extended] 79 | 80 | ## Document Structure 81 | 82 | If in doubt how to organize your chapter or section, the following structure has proven useful for most cases: 83 | 84 | - Introduction 85 | - Installation 86 | - Configuration 87 | - Troubleshooting 88 | 89 | ## More Information 90 | 91 | - [The AsciiDoc Recommended Practices](https://asciidoctor.org/docs/asciidoc-recommended-practices/) 92 | - [The ownCloud Documentation Best Practices](https://github.com/owncloud/docs/blob/master/docs/best-practices.md) 93 | -------------------------------------------------------------------------------- /docs/test-ui-bundle.md: -------------------------------------------------------------------------------- 1 | # Testing un-merged docs-ui changes 2 | 3 | If you want to test an un-merged change made in the `docs-ui` repository with content from the ownCloud documentation, build the documentation as usual with the Antora command but add the option `--ui-bundle-url /ui-bundle.zip` to your command. The location for this bundle is in the `docs-ui` repository in directory `build/`. More details for prerequisites and how to create the `ui-bundle.zip` can be found in the [docs-ui](https://github.com/owncloud/docs-ui#owncloud-documentation-ui) repository. 4 | 5 | The following example assumes: 6 | 7 | - You are in the root directory of your local `docs` repository 8 | - The `docs-ui` repository directory is on the same directory level as `docs` 9 | - You have `ui-bundle.zip` manually created with [gulp pack](https://github.com/owncloud/docs-ui#preview-changes-using-owncloud-documentation) 10 | - You have a webserver pointing to the `public` directory in your local `docs` repository to access the built documentation 11 | 12 | ```console 13 | npm antora \ 14 | --ui-bundle-url ../docs/build/ui-bundle.zip \ 15 | --url http://localhost:8080 16 | ``` 17 | 18 | If the build returns without an error, open the documentation with your browser to see your changes. 19 | -------------------------------------------------------------------------------- /docs/the-branching-workflow.md: -------------------------------------------------------------------------------- 1 | # The Branching Workflow 2 | 3 | The Docs repo itself is not versioned as it assembles other doc repos and other doc repos might use versioning. For any repo that uses versioning, changes in that repo must be made in master and backported to the corresponding branch if applicable. Usually only 2 working branches and master named `next` are maintained. Any documentation that is versioned can use `latest` in the URL instead of a branch number which points automatically to the latest stable branch of the corresponding documentation. 4 | 5 | See the **Create a New Version Branch** documentation link in each doc repo readme for details how to do versioning if applicable. 6 | -------------------------------------------------------------------------------- /docs/the-build-pipeline.md: -------------------------------------------------------------------------------- 1 | # Build Pipeline and Web Deployment 2 | 3 | ownCloud uses Drone for building and deploying the documentation. 4 | Drone is a [Continuous Delivery](https://www.continuousdelivery.com/) platform that helps optimize and automate software delivery. 5 | 6 | The build pipeline is configured in [.drone.yml](https://github.com/owncloud/docs/blob/master/.drone.yml), located in the root directory of the docs repository. You can view the current build status of the docs at https://drone.owncloud.com/owncloud/docs. 7 | 8 | Every push to the docs master branch triggers a drone build. At the end of the build process, the docs are deployed to production. 9 | 10 | It's outside the scope of this file to discuss the process or [the `.drone.yml` file format](https://0-8-0.docs.drone.io/) in-depth. 11 | However, in essence, here is how the build pipeline works: 12 | 13 | 1. The docs repository is cloned. 14 | 1. All required dependencies are installed. 15 | 1. All referenced content sources are added 16 | 1. The documentation is validated. 17 | 1. The documentation is built. 18 | 1. The HTML version of the documentation is deployed. 19 | 1. A build notification is sent. 20 | 21 | ## Build Notifications 22 | 23 | Build notifications are sent to the `#documentation` channel in https://talk.owncloud.com when a full docs build fails. Notifications are not sent for successful builds. 24 | 25 | No Pull Request notifications are sent to the `#documentation` channel, as this information is visible within the Pull Request details. 26 | 27 | If you're not already a member of the channel, please join, so that you know what's happening with the builds. 28 | -------------------------------------------------------------------------------- /docs/what-is-antora.md: -------------------------------------------------------------------------------- 1 | # Antora 2 | 3 | [Antora](https://antora.org) is self-described as: 4 | 5 | > The multi-repository documentation site generator for tech writers who :heart: writing in AsciiDoc. 6 | 7 | While relatively new (*currently at release 2.0.0*), it's already a competent tool; one I expect makes developers' lives much more comfortable than competing platforms. This is because Antora is: 8 | 9 | - Based around [the AsciiDoc format](https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/), a format far more akin to Markdown. Its syntax is _readable_, _concise_, _comprehensive_, _extensible_, and, above all, _easy to learn_. 10 | - Provides a logical and structured way of organizing technical documentation. 11 | - Enforces a clear and logical separation of text content and supporting assets (such as *images*, *videos*, and *code*). 12 | - Uses a small set of tools, ones that are commonly available in developer tool sets, such as *Node* and *Git*. 13 | - Provides very flexible project navigation. 14 | - Natively links to different documentation versions within the UI; 15 | - _Plus so much more!_ 16 | 17 | ### What Antora Docs Look Like 18 | 19 | ![The ownCloud docs on Antora](./images/antora-ui-anotated.png) 20 | 21 | In the screenshot above, you can see an example of what Antora documentation looks like (using a slightly modified default theme). You can see that: 22 | 23 | - The standard main navigation is at the top(1). 24 | - The secondary navigation is down the left-hand side(2). 25 | - There is breadcrumb navigation above the main content(3). 26 | - The main content is in a large pane on the right(4). 27 | 28 | While not revolutionary, the layout uses well-recognized and understood navigation conventions. However, it has a rich navigational feature. Notice the link right at the bottom(5). If you click it, it opens up a sub-navigation menu. 29 | 30 | ![Antora documentation version navigation](./images/what-is-antora/the-antora-version-changer.gif) 31 | 32 | This is an excellent, time-saving feature that allows for direct navigation between different documentation versions (git branches). In the current documentation, an extra page exists to link to the various versions of the documentation, such as for version *8.2*, *9.x*, and *10.x.* However, by taking advantage of this feature in Antora, that's not necessary, thanks to this innovative feature. 33 | 34 | I expect that it makes users lives so much easier, as they'll be able to navigate quickly to the version of the documentation that matches their ownCloud installation. 35 | 36 | ## The Antora Directory Structure 37 | 38 | Now that you have an overview of what Antora is and how it renders documentation, the next thing you need to do is to understand the Antora directory structure. That way you know where to find and create files. 39 | 40 | I could describe it here, but [the Antora documentation](https://docs.antora.org/antora/1.0/component-structure/) does an excellent job already. So go through the information and get yourself acquainted. 41 | -------------------------------------------------------------------------------- /docs/what-is-asciidoc.md: -------------------------------------------------------------------------------- 1 | # What is AsciiDoc? 2 | 3 | To quote [the AsciiDoc Syntax Quick Reference Guide](https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/) (which you should bookmark*!*): 4 | 5 | > AsciiDoc is a lightweight markup language for authoring notes, articles, documentation, books, web pages, slide decks and man pages in plain text. This guide is a quick reference for the common AsciiDoc document and text formatting markup. 6 | 7 | If you look through the guide, you'll see that it's a file format which is quite similar to Markdown, supporting paragraphs, formatted text, headers, sections, section titles, lists, links, images, code, tables, videos, and so much more. 8 | 9 | What's more, the format is **consistent** and **predictable**, as it has a definitive standard. 10 | This is in stark contrast to Markdown, which has a series of (_often competing_) standards, such as [GitHub Flavoured Markdown](https://guides.github.com/features/mastering-markdown/), and [Daring Fireball](https://daringfireball.net/projects/markdown/). 11 | 12 | AsciiDoc is a robust, text-based file format, which you can use to create even the most sophisticated technical documentation, able to be exported to a range of modern file formats. 13 | Have a look through the quick reference guide, and the rest of the official AsciiDoc documentation to learn more. 14 | 15 | ## Writing & Editing AsciiDoc Files 16 | 17 | To contribute to the documentation, you're only going to need 3 things; these are: 18 | 19 | 1. A text editor with AsciiDoc syntax support available. 20 | 2. An AsciiDoc previewer. 21 | 3. AsciiDoc documentation 22 | 23 | Let's step through each one. 24 | 25 | ## A Text Editor or an IDE 26 | 27 | Just like writing in any other format or computer language, you're going to need a text editor or an IDE. 28 | And as you're a developer, you'll already have one, and it likely supports AsciiDoc already. 29 | If not there should be a plugin available for it. 30 | Here are some text editors and IDEs that we recommend. 31 | 32 | ### VIM 33 | 34 | ![Editing AsciiDoc in Vim](./images/editing-asciidoc-in-vim.png) 35 | 36 | If you're using VIM (or VI), there are two plugins that you can make use of; these are dahu/vim-asciidoc, and matcatc/vim-asciidoc-folding. 37 | vim-asciidoc provides enhanced editing support for Asciidoc files. 38 | vim-asciidoc-folding allows vim to enable folding asciidoc files. 39 | 40 | Alternatively, if you want both of these, plus some extra setup ready to go, you can use [the Vim for Technical Writers repository](https://github.com/settermjd/vim-for-technical-writers). 41 | The repository has a `.vimrc` file that installs both plugins, enabling them only when editing Asciidoc files. 42 | 43 | ### SublimeText 44 | 45 | ![Editing AsciiDoc in SublimeText](./images/editing-asciidoc-in-sublime-text.png) 46 | 47 | SublimeText doesn't come with native support for AsciiDoc, but you can install [the AsciiDoc package](https://github.com/asciidoctor/sublimetext-asciidoc) which provides it. 48 | Once you do that, you'll have a range of AsciiDoc editing functionality available, including: 49 | 50 | - Snippets 51 | - Syntax Highlighting 52 | - Keymaps 53 | - Attribute completion 54 | - Display document and section titles in the local symbol list 55 | 56 | ### Atom 57 | 58 | ![Editing AsciiDoc in Visual Studio Code](./images/editing-asciidoc-in-atom.png) 59 | 60 | In recent months, Atom's been gaining significant traction. 61 | Written primarily by the team at GitHub and supported by a massive community around the world, and packed with a wide range of features out of the box, it's easy to see why. 62 | 63 | If it's your text editor of choice, install the [asciidoc-assistant](https://atom.io/packages/asciidoc-assistant) package. 64 | This package is a meta-package that takes care of installing a range of plugins, which to give you full AsciiDoc support. 65 | 66 | These are: 67 | 68 | - [language-asciidoc:](https://atom.io/packages/language-asciidoc) This package adds syntax highlighting and snippets to AsciiDoc files. 69 | - [asciidoc-image-helper:](https://atom.io/packages/asciidoc-image-helper) This package facilitates insertion of images in an AsciiDoc document. 70 | - [asciidoc-preview:](https://github.com/asciidoctor/atom-asciidoc-preview) This package allows Atom to show the rendered HTML of the AsciiDoc content in the current editor. 71 | - [autocomplete-asciidoc:](https://atom.io/packages/autocomplete-asciidoc) This package provides AsciiDoc language auto-completions in Atom. 72 | 73 | **Note:** to view images in the preview pane, you have to set the `imagesdir` attribute in the AsciiDoc plugin's preferences. 74 | To do that: 75 | 76 | 1. Open the Preferences pane for the "_asciidoc-preview_" package. 77 | 2. In the "_Default Attributes_" field, under "Settings", add _the absolute path_ to the image directory for one of the modules, at the end of the existing attributes. 78 | 79 | ![Setting the AsciiDoc plugin's imagesdir attribute in Atom.](./images/what-is-asciidoc/setting-imagesdir-in-atom.png) 80 | 81 | Unfortunately, you cannot reference multiple image directories. 82 | 83 | ### Visual Studio Code 84 | 85 | ![Editing AsciiDoc in Visual Studio Code](./images/editing-asciidoc-in-vscode.png) 86 | 87 | If you're on the Microsoft Windows platform or love the Visual Studio environment — and in particular the new "*Code*" editor/IDE — then you'll be happy to know that it supports AsciiDoc as well. 88 | If you install [the AsciiDoc plugin](https://marketplace.visualstudio.com/items?itemName=joaompinto.asciidoctor-vscode), then you'll get some basic functionality, including: 89 | 90 | - Live preview. 91 | - Syntax highlighting. 92 | - Open Preview to the Side. 93 | - View Symbols and Go to Symbol actions. 94 | 95 | **Note:** I’m not, currently, aware of how to enable rendering images in the preview pane. 96 | 97 | ### IntelliJ IDEA 98 | 99 | ![Editing AsciiDoc in PhpStorm](./images/editing-asciidoc-in-phpstorm.png) 100 | 101 | If you're a fan of IDEs over text editors, in particular, the JetBrains IntelliJ platform, then make sure you install [the AsciiDoc plugin](https://plugins.jetbrains.com/plugin/7391-asciidoc), available, from the JetBrains repository. 102 | 103 | It provides a minimal set of functionality when editing AsciiDoc files, which includes: 104 | 105 | - Live Preview (show editor and preview, the editor only, and preview only). 106 | - Basic formatting toolbar (bold, italics, mono-spaced). 107 | - Code folding. 108 | - Syntax highlighting. 109 | - Convert non-AsciiDoc files to AsciiDoc. 110 | 111 | **Note:** to view images in the preview pane, you have to set the `imagesdir` attribute in the AsciiDoc plugin's preferences. 112 | To do that: 113 | 114 | 1. Open the Preferences pane and filter by `"AsciiDoc"`. 115 | 2. In the "_Attributes_" field, add a new entry, where "_Key_" is set to `imagesdir` and "_Value_" is set to _the absolute path_ to the image directory for one of the modules. 116 | 3. Click either "_Apply_" or "_OK_". 117 | 118 | ![Setting the AsciiDoc plugin's imagesdir attribute in IntelliJ.](./images/what-is-asciidoc/setting-imagesdir-in-intellij.png) 119 | 120 | Unfortunately, you cannot reference multiple image directories, whether by using a regular expression, nor can you specify `imagesdir` multiple times. 121 | 122 | ### Using Another Text Editor or IDE? 123 | 124 | If you're not already using one of these text editors of IDEs, don't feel the need to change to them, just because they're what we recommend. 125 | It's possible that your existing text editor or IDE already has an AsciiDoc plugin. 126 | And it makes far more sense to continue using what you already know, instead of learning an entirely new tool. 127 | 128 | ## An AsciiDoc Previewer 129 | 130 | ![Viewing AsciiDoc in Firefox with the Asciidoc Live Preview Plugin](./images/viewing-asciidoc-in-firefox-with-the-asciidoc-live-preview-plugin.png) 131 | 132 | Once your text editor or IDE is ready to work with AsciiDoc then, assuming it doesn't already support previewing AsciiDoc, you’ll need a way to preview the changes you’re making to ensure that they render as you expect. 133 | 134 | For that, assuming that you’re using one of _Google Chrome_, _Mozilla Firefox_, or _Opera_, you need to install the [AsciiDoc Live Preview plugin](https://asciidoctor.org/docs/editing-asciidoc-with-live-preview/). 135 | When installed, enable the AsciiDoc Live Preview plugin, and you will see AsciiDoc files rendered as HTML in the browser. 136 | 137 | ## AsciiDoc Documentation 138 | 139 | As with anything of a technical nature, you need documentation, because there’s going to come a time that you will need to refer to it. 140 | So too with AsciiDoc. 141 | Here are a set of links to documentation that you can bookmark and use on a regular basis: 142 | 143 | - [The AsciiDoc Syntax Quick Reference Guide](https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/) 144 | - [Powerman's AsciiDoc Cheatsheet](https://powerman.name/doc/asciidoc) 145 | - [The AsciiDoc Markup Syntax Summary](https://is.muni.cz/el/1433/podzim2015/PB162/um/printable/asciidoc.html) 146 | -------------------------------------------------------------------------------- /es-docker-compose.yml: -------------------------------------------------------------------------------- 1 | services: 2 | elasticsearch: 3 | image: elasticsearch:7.17.15 4 | ports: 5 | - 9200:9200 6 | - 9300:9300 7 | environment: 8 | - discovery.type=single-node 9 | - xpack.security.enabled=false 10 | -------------------------------------------------------------------------------- /ext-antora/attributes-used-in-antora-yml.js: -------------------------------------------------------------------------------- 1 | 'use strict' 2 | 3 | // Console print antora.yml attributes used per component 4 | 5 | module.exports.register = function () { 6 | this.once('contentClassified', ({ playbook, contentCatalog }) => { 7 | console.log('antora-playbook.yml attributes') 8 | console.log(playbook.asciidoc.attributes) 9 | contentCatalog.getComponents().forEach((component) => { 10 | component.versions.forEach((componentVersion) => { 11 | getUniqueOrigins(contentCatalog, componentVersion).forEach((origin) => { 12 | console.log(`antora.yml attributes (${componentVersion.version}@${componentVersion.name})`) 13 | console.log(origin.descriptor.asciidoc?.attributes || {}) 14 | }) 15 | }) 16 | }) 17 | }) 18 | } 19 | 20 | function getUniqueOrigins (contentCatalog, componentVersion) { 21 | return contentCatalog.findBy({ component: componentVersion.name, version: componentVersion.version }).reduce((origins, file) => { 22 | const origin = file.src.origin 23 | if (origin && !origins.includes(origin)) origins.push(origin) 24 | return origins 25 | }, []) 26 | } 27 | -------------------------------------------------------------------------------- /ext-antora/attributes-used-in-site-yml.js: -------------------------------------------------------------------------------- 1 | 'use strict' 2 | 3 | // Console print site.yml attributes used per component build 4 | 5 | module.exports.register = function () { 6 | this.once('contentClassified', ({ siteAsciiDocConfig, contentCatalog }) => { 7 | console.log('site-wide attributes') 8 | console.log(siteAsciiDocConfig.attributes) 9 | contentCatalog.getComponents().forEach((component) => { 10 | component.versions.forEach((componentVersion) => { 11 | console.log(`${componentVersion.version}@${componentVersion.name} attributes`) 12 | console.log(componentVersion.asciidoc.attributes) 13 | }) 14 | }) 15 | }) 16 | } 17 | -------------------------------------------------------------------------------- /ext-antora/comp-version.js: -------------------------------------------------------------------------------- 1 | 'use strict' 2 | 3 | /** 4 | * Print a table of Component - Version - Number of Files + total. 5 | * Only the number of files in the modules directory are counted 6 | * Version 1.1.0 7 | * 8 | * ┌─────────┬────────┬─────────┬───────┐ 9 | * │ (index) │ Name │ Version │ Files │ 10 | * ├─────────┼────────┼─────────┼───────┤ 11 | * │ 0 │ 'ROOT' │ '~' │ 14 │ 12 | * │ 3 │ │ │ 14 │ 13 | * └─────────┴────────┴─────────┴───────┘ 14 | */ 15 | 16 | module.exports.register = function () { 17 | this.once('contentAggregated', ({ contentAggregate }) => { 18 | console.log('\nProcessing the following components, versions and number of files\n') 19 | var total_files = 0 20 | const component_table = [] 21 | contentAggregate.forEach((bucket) => { 22 | var count = 0 23 | bucket.files.forEach((file) => { 24 | if (file.src.path.startsWith('modules')) { 25 | count += 1 26 | } 27 | }) 28 | component_table.push ({Name: bucket.name, Version: bucket.version || '~', Files: count}) 29 | total_files += count 30 | }) 31 | component_table.push ({Files: total_files}) 32 | console.table(component_table) 33 | console.log() // do not delete, else we get a double empty line 34 | }) 35 | } 36 | -------------------------------------------------------------------------------- /ext-antora/generate-index.js: -------------------------------------------------------------------------------- 1 | 'use strict' 2 | 3 | // Antora extension to create a new and clean search index based on ElasticSearch 4 | 5 | const _ = require('lodash') 6 | const cheerio = require('cheerio') 7 | const Entities = require('html-entities') 8 | const { Client } = require('@elastic/elasticsearch') 9 | 10 | module.exports.register = function () { 11 | // run when the Antora site publishing event has been fired = all done 12 | // get all the pages created and index the result 13 | this.on('sitePublished', ({ playbook, contentCatalog }) => { 14 | const pages = contentCatalog.getPages() 15 | generateIndex(playbook, pages) 16 | }) 17 | } 18 | 19 | async function generateIndex(playbook, pages) { 20 | // this env is usually not set when building local - skip indexing 21 | // but when set, we index, also when building local 22 | // only set in .drone.star in the docs repo when doing a full build 23 | if (process.env.UPDATE_SEARCH_INDEX !== 'true') { 24 | console.log('ElasticSearch: index generation skipped') 25 | return 26 | } else { 27 | console.log('ElasticSearch: indexing requested') 28 | } 29 | 30 | // note that the following envvars are required to build the index 31 | // see the documentation at docs/README.md and docs-ui/src/partials/header-content.hbs for more information 32 | if (!process.env.ELASTICSEARCH_NODE) { 33 | console.log('ElasticSearch: ELASTICSEARCH_NODE envvar is missing, indexing skipped') 34 | return 35 | } 36 | if (!process.env.ELASTICSEARCH_INDEX) { 37 | console.log('ElasticSearch: ELASTICSEARCH_INDEX envvar is missing, indexing skipped') 38 | return 39 | } 40 | if (!process.env.ELASTICSEARCH_WRITE_AUTH) { 41 | console.log('ElasticSearch: ELASTICSEARCH_WRITE_AUTH envvar is missing, indexing skipped') 42 | return 43 | } 44 | 45 | let siteUrl = playbook.site.url 46 | if (!siteUrl) { 47 | siteUrl = '' 48 | } 49 | 50 | const index_start = Date.now() 51 | 52 | // index the documents available 53 | const documents = pages.map((page) => { 54 | // a document like '_email-config.adoc' gets excluded from the catalog 55 | // because it has a leading '_' which will result in an undefined 56 | // 'page.pub.url' variable breaking generating the index 57 | if (page.pub === undefined) { 58 | return 59 | } 60 | 61 | const titles = [] 62 | 63 | const html = page.contents.toString() 64 | // for performance reasons, we use parameter xml which then uses the htmlparser2 engine. 65 | // for more details see: 66 | // https://cheerio.js.org/docs/api/interfaces/CheerioOptions 67 | // https://github.com/taoqf/node-html-parser#performance 68 | const $ = cheerio.load(html, { xml: true }) 69 | 70 | const $article = $('article') 71 | const title = $article.find('h1').text() 72 | 73 | $article.find('h1,h2,h3,h4,h5,h6').each(function () { 74 | let $title = $(this) 75 | let id = $title.attr('id') 76 | 77 | titles.push({ 78 | text: $title.text(), 79 | id: $title.attr('id'), 80 | url: siteUrl + page.pub.url + '#' + $title.attr('id') 81 | }) 82 | 83 | $title.remove() 84 | }) 85 | 86 | let text = Entities.decode($('article').text()) 87 | .replace(/(<([^>]+)>)/gi, '') 88 | .replace(/\n/g, ' ') 89 | .replace(/\r/g, ' ') 90 | .replace(/\s+/g, ' ') 91 | .trim() 92 | 93 | // todo, we want to do more fancy stuff with results 94 | // also see: docs-ui/src/js/vendor/elastic.js 95 | return { 96 | component: page.src.component, 97 | version: page.src.version, 98 | name: page.src.stem, 99 | title: title, 100 | text: text, 101 | url: siteUrl + page.pub.url, 102 | titles: titles 103 | } 104 | }) 105 | 106 | // prepare index for uploading 107 | let result = [] 108 | documents.forEach((document, index) => { 109 | result.push({ 110 | index: { 111 | _index: process.env.ELASTICSEARCH_INDEX, 112 | _type: 'page', 113 | _id: index 114 | } 115 | }) 116 | 117 | result.push(document) 118 | }) 119 | 120 | // create a new client to connect 121 | const client = new Client({ 122 | node: process.env.ELASTICSEARCH_NODE, 123 | auth: { 124 | username: process.env.ELASTICSEARCH_WRITE_AUTH.split(':')[0], 125 | password: process.env.ELASTICSEARCH_WRITE_AUTH.split(':')[1] 126 | } 127 | }) 128 | 129 | // remove the old index and create/upload the new one 130 | try { 131 | console.log('ElasticSearch: remove old search index') 132 | await indexDelete(client) 133 | console.log('ElasticSearch: create empty search index') 134 | await indexCreate(client) 135 | console.log('ElasticSearch: upload search index') 136 | await indexBulk(client, result) 137 | } catch (err) { 138 | const errObj = JSON.parse(err) 139 | console.log('ElasticSearch: ERROR: ' + errObj.status + ' - ' + errObj.error.reason) 140 | process.exit(1) 141 | } 142 | const index_end = Date.now() 143 | const elapsedTime = (index_end - index_start) / 1000 144 | console.log(`ElasticSearch: indexing time: ${elapsedTime}s`) 145 | } 146 | 147 | function indexDelete(client) { 148 | return new Promise((resolve, reject) => { 149 | client.indices 150 | .delete({ 151 | index: process.env.ELASTICSEARCH_INDEX, 152 | ignore_unavailable: true 153 | }) 154 | .then((resp) => { 155 | resolve(resp) 156 | }) 157 | .catch((err) => { 158 | console.warn(err) 159 | resolve(true) 160 | }) 161 | }) 162 | } 163 | 164 | function indexCreate(client) { 165 | return new Promise((resolve, reject) => { 166 | client.indices 167 | .create({ 168 | index: process.env.ELASTICSEARCH_INDEX 169 | }) 170 | .then((resp) => { 171 | resolve(resp) 172 | }) 173 | .catch((err) => { 174 | reject(err) 175 | }) 176 | }) 177 | } 178 | 179 | function indexBulk(client, result) { 180 | return new Promise((resolve, reject) => { 181 | client 182 | .bulk({ 183 | body: result 184 | }) 185 | .then((resp) => { 186 | resolve(resp) 187 | }) 188 | .catch((err) => { 189 | reject(err) 190 | }) 191 | }) 192 | } 193 | -------------------------------------------------------------------------------- /ext-antora/load-global-site-attributes.js: -------------------------------------------------------------------------------- 1 | // v1.0.0 2 | "use strict" 3 | 4 | const fs = require('fs') 5 | const http = require('http') 6 | const https = require('https') 7 | const yaml = require('js-yaml') 8 | 9 | // this extension loads (global) attributes into the playbook (site.yml) 10 | // !! attributes in the playbook take precedence over loaded attributes !! 11 | // allows test building a repo like in multi repo envs with custom local attribute values 12 | // you can temporarily disable loading by setting 'enabled: false' 13 | // error handling: 14 | // if no 'attributefile' is configured: warn, but continue processing 15 | // if loading or processing the file caused an error (like file not found, needs fixing): stop 16 | 17 | module.exports.register = function ({ config }) { 18 | const logger = this.getLogger('load-global-site-attributes-extension') 19 | let attrib_file = '' 20 | let attrib_yaml = {} 21 | let orig_playbook = {} 22 | let result = {} 23 | 24 | this.on("playbookBuilt", async ({ playbook }) => { 25 | // get the original playbook asciidoc attributes, note it can be empty 26 | orig_playbook = JSON.parse(JSON.stringify(playbook.asciidoc.attributes)) || {} 27 | 28 | // only if attributefile is configured in site.yml pointing to a resource (file or url) 29 | if (config.attributefile) { 30 | try { 31 | // define the get function to use and load the file 32 | if (config.attributefile.startsWith('http')) { 33 | attrib_file = await get_file_from_url(config.attributefile) 34 | } else { 35 | attrib_file = await get_file_from_local(config.attributefile) 36 | } 37 | 38 | // convert and update 39 | attrib_yaml = await convert_yaml(attrib_file) 40 | result = Object.assign(attrib_yaml, playbook.asciidoc.attributes) 41 | playbook.asciidoc.attributes = result 42 | this.updateVariables( playbook ) 43 | 44 | // loading or processing the file caused an error 45 | } catch (error) { 46 | logger.error(error) 47 | this.stop() 48 | } 49 | } else { 50 | logger.warn('attributefile is not configured in the playbook (site.yml).') 51 | } 52 | // console.log(this.getVariables()) 53 | }) 54 | } 55 | 56 | function get_file_from_url(url) { 57 | // promise a file from url 58 | // when executed it returns the contents if found 59 | return new Promise((resolve, reject) => { 60 | const client = url.startsWith('https') ? https : http 61 | const req = client.request(url, (res) => { 62 | if (res.statusCode < 200 || res.statusCode >= 300) { 63 | reject(`Request Failed.\n` + 64 | `Status Code: ${res.statusCode}\n` + 65 | `${url}`) 66 | } 67 | var body = [] 68 | res.on('data', function(chunk) { 69 | body.push(chunk) 70 | }) 71 | res.on('end', function() { 72 | try { 73 | body = Buffer.concat(body).toString() 74 | } catch(error) { 75 | reject(error) 76 | } 77 | resolve(body) 78 | }) 79 | }) 80 | req.on('error', (error) => { 81 | reject(error.message) 82 | }) 83 | // send the request 84 | req.end() 85 | }) 86 | } 87 | 88 | function get_file_from_local(file) { 89 | // promise a file from local filesystem 90 | // when executed it returns the contents if found 91 | return new Promise((resolve, reject) => { 92 | fs.readFile(file, 'utf8', (error, data) => { 93 | if (error) reject(error) 94 | resolve(data) 95 | }) 96 | }) 97 | } 98 | 99 | function convert_yaml(data) { 100 | // promise to parse yaml data 101 | // when executed it returns the parsed contents 102 | return new Promise((resolve, reject) => { 103 | try { 104 | var d = yaml.load(data) 105 | // the parser found an error, no object will be returned 106 | } catch (error) { 107 | reject(`yaml parser: ` + error) 108 | } 109 | resolve(d) 110 | }) 111 | } 112 | -------------------------------------------------------------------------------- /ext-asciidoc/remote-include-processor.js: -------------------------------------------------------------------------------- 1 | /** 2 | * This script mimics the capability of Asciidoc: 3 | * Including content by URI in Antora 4 | * https://docs.asciidoctor.org/asciidoc/latest/directives/include-uri/#reference-include-content-by-uri 5 | * e.g.: include::https://raw.githubusercontent.com/asciidoctor/asciidoctor/master/README.adoc[] 6 | * 7 | * Note check if you need a leveloffset like [leveloffset=+1] 8 | * This may be necessary for the makepdf script to avoid having the included content starting on a separate page. 9 | * 10 | * Note that the makepdf script needs to have the 'allow-uri-read="" ' attribute param set in the code. 11 | * 12 | * Note that no attributes in the included document can be resolved if they are defined outside of this repo 13 | * 14 | * Source: 15 | * Add support for including content from a URL (i.e., remote include) 16 | * https://gitlab.com/antora/antora/-/issues/246 17 | * https://github.com/feelpp/book.feelpp.org/blob/master/lib/remote-include-processor.js 18 | */ 19 | const CIRCUMFIX_COMMENT_SUFFIX_RX = / (?:\*[/)]|--%?>)$/ 20 | const NEWLINE_RX = /\r\n?|\n/ 21 | const TAG_DELIMITER_RX = /[,;]/ 22 | const TAG_DIRECTIVE_RX = /\b(?:tag|(end))::(\S+)\[\]$/ 23 | const LINES_DOTDOT_RX = /\.\./ 24 | 25 | 26 | function getTags (attrs) { 27 | if ( 'tag' in attrs ) { 28 | const tag = attrs['tag'] 29 | if (tag && tag !== '!') { 30 | return tag.charAt() === '!' ? new Map().set(tag.substr(1), false) : new Map().set(tag, true) 31 | } 32 | } else if ( 'tags' in attrs ) { 33 | const tags = attrs['tags'] 34 | if (tags) { 35 | let result = new Map() 36 | let any = false 37 | tags.split(TAG_DELIMITER_RX).forEach((tag) => { 38 | if (tag && tag !== '!') { 39 | any = true 40 | tag.charAt() === '!' ? result.set(tag.substr(1), false) : result.set(tag, true) 41 | } 42 | }) 43 | if (any) return result 44 | } 45 | } 46 | } 47 | 48 | 49 | function applyTagFiltering (contents, tags) { 50 | let selecting, selectingDefault, wildcard 51 | if (tags.has('**')) { 52 | if (tags.has('*')) { 53 | selectingDefault = selecting = tags.get('**') 54 | wildcard = tags.get('*') 55 | tags.delete('*') 56 | } else { 57 | selectingDefault = selecting = wildcard = tags.get('**') 58 | } 59 | tags.delete('**') 60 | } else { 61 | selectingDefault = selecting = !Array.from(tags.values()).includes(true) 62 | if (tags.has('*')) { 63 | wildcard = tags.get('*') 64 | tags.delete('*') 65 | } 66 | } 67 | 68 | const lines = [] 69 | const tagStack = [] 70 | const usedTags = [] 71 | let activeTag 72 | let lineNum = 0 73 | let startLineNum 74 | contents.split(NEWLINE_RX).forEach((line) => { 75 | lineNum++ 76 | let m 77 | let l = line 78 | if ( 79 | (l.endsWith('[]') || 80 | (~l.indexOf('[] ') && 81 | (m = l.match(CIRCUMFIX_COMMENT_SUFFIX_RX)) && 82 | (l = l.substr(0, m.index)).endsWith('[]'))) && 83 | (m = l.match(TAG_DIRECTIVE_RX)) 84 | ) { 85 | const thisTag = m[2] 86 | if (m[1]) { 87 | if (thisTag === activeTag) { 88 | tagStack.shift() 89 | ;[activeTag, selecting] = tagStack.length ? tagStack[0] : [undefined, selectingDefault] 90 | } else if (tags.has(thisTag)) { 91 | const idx = tagStack.findIndex(([name]) => name === thisTag) 92 | if (~idx) { 93 | tagStack.splice(idx, 1) 94 | //console.warn(`line ${lineNum}: mismatched end tag in include: expected ${activeTag}, found ${thisTag}`) 95 | } 96 | //} else { 97 | // //console.warn(`line ${lineNum}: unexpected end tag in include: ${thisTag}`) 98 | //} 99 | } 100 | } else if (tags.has(thisTag)) { 101 | usedTags.push(thisTag) 102 | tagStack.unshift([(activeTag = thisTag), (selecting = tags.get(thisTag))]) 103 | } else if (wildcard !== undefined) { 104 | selecting = activeTag && !selecting ? false : wildcard 105 | tagStack.unshift([(activeTag = thisTag), selecting]) 106 | } 107 | } else if (selecting) { 108 | if (!startLineNum) startLineNum = lineNum 109 | lines.push(line) 110 | } 111 | }) 112 | // Q: use _.difference(Object.keys(tags), usedTags)? 113 | //const missingTags = Object.keys(tags).filter((e) => !usedTags.includes(e)) 114 | //if (missingTags.length) { 115 | // console.warn(`tag${missingTags.length > 1 ? 's' : ''} '${missingTags.join(',')}' not found in include`) 116 | //} 117 | return [lines, startLineNum || 1] 118 | } 119 | 120 | 121 | function getLines (attrs) { 122 | if ( 'lines' in attrs ) { 123 | const lines = attrs['lines'] 124 | if (lines) { 125 | // console.warn(`have lines` + lines) 126 | let result = [] // new Map() 127 | let any = false 128 | lines.split(TAG_DELIMITER_RX).forEach((line) => { 129 | if (line && line !== '!') { 130 | let tryMultipleLines = line.split(LINES_DOTDOT_RX) 131 | if ( tryMultipleLines.length === 1 ) { 132 | any = true 133 | result.push([tryMultipleLines[0], tryMultipleLines[0]]) 134 | } 135 | else if ( tryMultipleLines.length === 2 ) { 136 | any = true 137 | result.push([tryMultipleLines[0], tryMultipleLines[1]]) 138 | } 139 | } 140 | }) 141 | if (any) return result 142 | } 143 | } 144 | } 145 | 146 | function applyLineFiltering (contents, linesToInclude) { 147 | const lines = [] 148 | let lineNum = 0 149 | let startLineNum 150 | let registerCurrentLine = false 151 | 152 | const nLinesPair = linesToInclude.length 153 | let currentLinePair = 0 154 | let startLine = linesToInclude[currentLinePair][0] 155 | let endLine = linesToInclude[currentLinePair][1] 156 | // console.warn(`applyLineFiltering ` + startLine + ' and ' + endLine ) 157 | 158 | contents.split(NEWLINE_RX).forEach((line) => { 159 | lineNum++ 160 | 161 | if ( !registerCurrentLine ) { 162 | if ( lineNum == startLine ) 163 | registerCurrentLine = true 164 | } 165 | 166 | if ( registerCurrentLine ) 167 | { 168 | if (!startLineNum) startLineNum = lineNum 169 | lines.push(line) 170 | 171 | if ( lineNum == endLine ) { 172 | registerCurrentLine = false 173 | currentLinePair++ 174 | if ( currentLinePair >= nLinesPair ) 175 | return [lines, startLineNum] 176 | else { 177 | startLine = linesToInclude[currentLinePair][0] 178 | endLine = linesToInclude[currentLinePair][1] 179 | } 180 | } 181 | } 182 | }) 183 | return [lines, startLineNum || 1] 184 | } 185 | 186 | module.exports = function () { 187 | this.includeProcessor(function () { 188 | this.$option('position', '>>') 189 | this.handles((target) => target.startsWith('https://')) 190 | this.process((doc, reader, target, attrs) => { 191 | const contents = require('child_process').execFileSync('curl', ['--silent', '-L', target], { encoding: 'utf8' }) 192 | let includeContents = contents 193 | let startLineNum = 1 194 | const tags = getTags(attrs) 195 | const lines = getLines(attrs) 196 | if (tags) [includeContents, startLineNum] = applyTagFiltering(includeContents, tags) 197 | else if (lines) [includeContents, startLineNum] = applyLineFiltering(includeContents, lines) 198 | reader.pushInclude(includeContents, target, target, startLineNum, attrs) 199 | // reader.pushInclude(contents, target, target, 1, attrs) 200 | }) 201 | }) 202 | } 203 | 204 | -------------------------------------------------------------------------------- /ext-asciidoc/tabs.js: -------------------------------------------------------------------------------- 1 | /** 2 | * Extends the AsciiDoc syntax to support a tabset element. The tabset is 3 | * created from a dlist that is enclosed in an example block marked with the 4 | * tabs style. 5 | * 6 | * Usage: 7 | * 8 | * [tabs] 9 | * ==== 10 | * Tab A:: 11 | * + 12 | * -- 13 | * Contents of tab A. 14 | * -- 15 | * Tab B:: 16 | * + 17 | * -- 18 | * Contents of tab B. 19 | * -- 20 | * ==== 21 | * 22 | * To use this extension, register the extension.js file with Antora (i.e., 23 | * list it as an AsciiDoc extension in the Antora playbook file), combine 24 | * styles.css with the styles for the site, and combine behavior.js with the 25 | * JavaScript loaded by the page. 26 | * 27 | * @author Dan Allen 28 | */ 29 | const IdSeparatorChar = '-' 30 | const InvalidIdCharsRx = /[^a-zA-Z0-9_]/g 31 | const List = Opal.const_get_local(Opal.module(null, 'Asciidoctor'), 'List') 32 | const ListItem = Opal.const_get_local(Opal.module(null, 'Asciidoctor'), 'ListItem') 33 | 34 | const generateId = (str, idx) => `tabset${idx}_${str.toLowerCase().replace(InvalidIdCharsRx, IdSeparatorChar)}` 35 | 36 | function tabsBlock () { 37 | this.onContext('example') 38 | this.process((parent, reader, attrs) => { 39 | const createHtmlFragment = (html) => this.createBlock(parent, 'pass', html) 40 | const tabsetIdx = parent.getDocument().counter('idx-tabset') 41 | const nodes = [] 42 | nodes.push(createHtmlFragment('
')) 43 | const container = this.parseContent(this.createBlock(parent, 'open'), reader) 44 | const sourceTabs = container.getBlocks()[0] 45 | if (!(sourceTabs && sourceTabs.getContext() === 'dlist' && sourceTabs.getItems().length)) return 46 | const tabs = List.$new(parent, 'ulist') 47 | tabs.addRole('tabs') 48 | const panes = {} 49 | sourceTabs.getItems().forEach(([[title], details]) => { 50 | const tab = ListItem.$new(tabs) 51 | tabs.$append(tab) 52 | const id = generateId(title.getText(), tabsetIdx) 53 | tab.text = `[[${id}]]${title.text}` 54 | let blocks = details.getBlocks() 55 | const numBlocks = blocks.length 56 | if (numBlocks) { 57 | if (blocks[0].context === 'open' && numBlocks === 1) blocks = blocks[0].getBlocks() 58 | panes[id] = blocks.map((block) => (block.parent = parent) && block) 59 | } 60 | }) 61 | nodes.push(tabs) 62 | nodes.push(createHtmlFragment('
')) 63 | Object.entries(panes).forEach(([id, blocks]) => { 64 | nodes.push(createHtmlFragment(`
`)) 65 | nodes.push(...blocks) 66 | nodes.push(createHtmlFragment('
')) 67 | }) 68 | nodes.push(createHtmlFragment('
')) 69 | nodes.push(createHtmlFragment('
')) 70 | parent.blocks.push(...nodes) 71 | }) 72 | } 73 | 74 | module.exports.register = (registry, context) => { 75 | registry.block('tabs', tabsBlock) 76 | } 77 | -------------------------------------------------------------------------------- /fonts/dejavu-sans-bold.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/owncloud/docs/08c13d3e438dbe6bd06b7ebab9dd6f215ed41719/fonts/dejavu-sans-bold.ttf -------------------------------------------------------------------------------- /fonts/dejavu-sans-boldoblique.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/owncloud/docs/08c13d3e438dbe6bd06b7ebab9dd6f215ed41719/fonts/dejavu-sans-boldoblique.ttf -------------------------------------------------------------------------------- /fonts/dejavu-sans-condensed.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/owncloud/docs/08c13d3e438dbe6bd06b7ebab9dd6f215ed41719/fonts/dejavu-sans-condensed.ttf -------------------------------------------------------------------------------- /fonts/dejavu-sans-condensedbold.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/owncloud/docs/08c13d3e438dbe6bd06b7ebab9dd6f215ed41719/fonts/dejavu-sans-condensedbold.ttf -------------------------------------------------------------------------------- /fonts/dejavu-sans-condensedboldoblique.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/owncloud/docs/08c13d3e438dbe6bd06b7ebab9dd6f215ed41719/fonts/dejavu-sans-condensedboldoblique.ttf -------------------------------------------------------------------------------- /fonts/dejavu-sans-condensedoblique.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/owncloud/docs/08c13d3e438dbe6bd06b7ebab9dd6f215ed41719/fonts/dejavu-sans-condensedoblique.ttf -------------------------------------------------------------------------------- /fonts/dejavu-sans-extralight.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/owncloud/docs/08c13d3e438dbe6bd06b7ebab9dd6f215ed41719/fonts/dejavu-sans-extralight.ttf -------------------------------------------------------------------------------- /fonts/dejavu-sans-mono-bold.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/owncloud/docs/08c13d3e438dbe6bd06b7ebab9dd6f215ed41719/fonts/dejavu-sans-mono-bold.ttf -------------------------------------------------------------------------------- /fonts/dejavu-sans-mono.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/owncloud/docs/08c13d3e438dbe6bd06b7ebab9dd6f215ed41719/fonts/dejavu-sans-mono.ttf -------------------------------------------------------------------------------- /fonts/dejavu-sans-monoboldoblique.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/owncloud/docs/08c13d3e438dbe6bd06b7ebab9dd6f215ed41719/fonts/dejavu-sans-monoboldoblique.ttf -------------------------------------------------------------------------------- /fonts/dejavu-sans-monooblique.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/owncloud/docs/08c13d3e438dbe6bd06b7ebab9dd6f215ed41719/fonts/dejavu-sans-monooblique.ttf -------------------------------------------------------------------------------- /fonts/dejavu-sans-oblique.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/owncloud/docs/08c13d3e438dbe6bd06b7ebab9dd6f215ed41719/fonts/dejavu-sans-oblique.ttf -------------------------------------------------------------------------------- /fonts/dejavu-sans.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/owncloud/docs/08c13d3e438dbe6bd06b7ebab9dd6f215ed41719/fonts/dejavu-sans.ttf -------------------------------------------------------------------------------- /fonts/dejavuserif-bold.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/owncloud/docs/08c13d3e438dbe6bd06b7ebab9dd6f215ed41719/fonts/dejavuserif-bold.ttf -------------------------------------------------------------------------------- /fonts/dejavuserif-bolditalic.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/owncloud/docs/08c13d3e438dbe6bd06b7ebab9dd6f215ed41719/fonts/dejavuserif-bolditalic.ttf -------------------------------------------------------------------------------- /fonts/dejavuserif-italic.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/owncloud/docs/08c13d3e438dbe6bd06b7ebab9dd6f215ed41719/fonts/dejavuserif-italic.ttf -------------------------------------------------------------------------------- /fonts/dejavuserif.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/owncloud/docs/08c13d3e438dbe6bd06b7ebab9dd6f215ed41719/fonts/dejavuserif.ttf -------------------------------------------------------------------------------- /fonts/dejavuserifcondensed-bold.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/owncloud/docs/08c13d3e438dbe6bd06b7ebab9dd6f215ed41719/fonts/dejavuserifcondensed-bold.ttf -------------------------------------------------------------------------------- /fonts/dejavuserifcondensed-bolditalic.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/owncloud/docs/08c13d3e438dbe6bd06b7ebab9dd6f215ed41719/fonts/dejavuserifcondensed-bolditalic.ttf -------------------------------------------------------------------------------- /fonts/dejavuserifcondensed-italic.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/owncloud/docs/08c13d3e438dbe6bd06b7ebab9dd6f215ed41719/fonts/dejavuserifcondensed-italic.ttf -------------------------------------------------------------------------------- /fonts/dejavuserifcondensed.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/owncloud/docs/08c13d3e438dbe6bd06b7ebab9dd6f215ed41719/fonts/dejavuserifcondensed.ttf -------------------------------------------------------------------------------- /fonts/mplus-1mn-bold.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/owncloud/docs/08c13d3e438dbe6bd06b7ebab9dd6f215ed41719/fonts/mplus-1mn-bold.ttf -------------------------------------------------------------------------------- /fonts/mplus-1mn-medium.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/owncloud/docs/08c13d3e438dbe6bd06b7ebab9dd6f215ed41719/fonts/mplus-1mn-medium.ttf -------------------------------------------------------------------------------- /fonts/mplus-1mn-regular.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/owncloud/docs/08c13d3e438dbe6bd06b7ebab9dd6f215ed41719/fonts/mplus-1mn-regular.ttf -------------------------------------------------------------------------------- /fonts/mplus-1mn-thin.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/owncloud/docs/08c13d3e438dbe6bd06b7ebab9dd6f215ed41719/fonts/mplus-1mn-thin.ttf -------------------------------------------------------------------------------- /fonts/mplus-1p-regular.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/owncloud/docs/08c13d3e438dbe6bd06b7ebab9dd6f215ed41719/fonts/mplus-1p-regular.ttf -------------------------------------------------------------------------------- /fonts/notoserif-bold.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/owncloud/docs/08c13d3e438dbe6bd06b7ebab9dd6f215ed41719/fonts/notoserif-bold.ttf -------------------------------------------------------------------------------- /fonts/notoserif-bold_italic.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/owncloud/docs/08c13d3e438dbe6bd06b7ebab9dd6f215ed41719/fonts/notoserif-bold_italic.ttf -------------------------------------------------------------------------------- /fonts/notoserif-italic.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/owncloud/docs/08c13d3e438dbe6bd06b7ebab9dd6f215ed41719/fonts/notoserif-italic.ttf -------------------------------------------------------------------------------- /fonts/notoserif-regular.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/owncloud/docs/08c13d3e438dbe6bd06b7ebab9dd6f215ed41719/fonts/notoserif-regular.ttf -------------------------------------------------------------------------------- /fonts/opensans-bold.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/owncloud/docs/08c13d3e438dbe6bd06b7ebab9dd6f215ed41719/fonts/opensans-bold.ttf -------------------------------------------------------------------------------- /fonts/opensans-bolditalic.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/owncloud/docs/08c13d3e438dbe6bd06b7ebab9dd6f215ed41719/fonts/opensans-bolditalic.ttf -------------------------------------------------------------------------------- /fonts/opensans-extrabold.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/owncloud/docs/08c13d3e438dbe6bd06b7ebab9dd6f215ed41719/fonts/opensans-extrabold.ttf -------------------------------------------------------------------------------- /fonts/opensans-extrabolditalic.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/owncloud/docs/08c13d3e438dbe6bd06b7ebab9dd6f215ed41719/fonts/opensans-extrabolditalic.ttf -------------------------------------------------------------------------------- /fonts/opensans-italic.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/owncloud/docs/08c13d3e438dbe6bd06b7ebab9dd6f215ed41719/fonts/opensans-italic.ttf -------------------------------------------------------------------------------- /fonts/opensans-light.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/owncloud/docs/08c13d3e438dbe6bd06b7ebab9dd6f215ed41719/fonts/opensans-light.ttf -------------------------------------------------------------------------------- /fonts/opensans-lightitalic.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/owncloud/docs/08c13d3e438dbe6bd06b7ebab9dd6f215ed41719/fonts/opensans-lightitalic.ttf -------------------------------------------------------------------------------- /fonts/opensans-regular.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/owncloud/docs/08c13d3e438dbe6bd06b7ebab9dd6f215ed41719/fonts/opensans-regular.ttf -------------------------------------------------------------------------------- /fonts/opensans-semibold.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/owncloud/docs/08c13d3e438dbe6bd06b7ebab9dd6f215ed41719/fonts/opensans-semibold.ttf -------------------------------------------------------------------------------- /fonts/opensans-semibolditalic.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/owncloud/docs/08c13d3e438dbe6bd06b7ebab9dd6f215ed41719/fonts/opensans-semibolditalic.ttf -------------------------------------------------------------------------------- /global-attributes.yml: -------------------------------------------------------------------------------- 1 | # global attributes loaded via extension 2 | # asciidoctor prefix for section IDs 3 | idprefix: '' 4 | idseparator: '-' 5 | # Antora User Interface Macros (btn, menu) 6 | experimental: true 7 | # Antora pagination (prev page, next page) 8 | page-pagination: true 9 | # Custom attribute page-component-build-list 10 | # Only embed named opengraph images in docs-ui via src/partials/head-meta-opengraph.hbs sourced from docs/overlay 11 | page-component-build-list: 'docs, docs-main, ocis, server, webui, desktop, android, ios-app, branding' 12 | # common 13 | docs-base-url: 'https://doc.owncloud.com' 14 | oc-complete-base-url: 'https://download.owncloud.com/server/stable' 15 | oc-contact-url: 'https://owncloud.com/contact/' 16 | oc-help-url: 'https://owncloud.com/docs-guides/' 17 | oc-marketplace-url: 'https://marketplace.owncloud.com' 18 | oc-central-url: 'https://central.owncloud.org' 19 | oc-support-url: 'https://owncloud.com/support' 20 | # 21 | # note that all attributes ending with '@' are used for versioned docs. the content can be 22 | # overwritten by the build process from the corresponding antory.yml file if populated - do not change 23 | # 24 | # docs 25 | latest-docs-version: 'next' 26 | previous-docs-version: 'next' 27 | # server 28 | latest-server-version: '10.15' 29 | latest-server-download-version: '10.15.2' 30 | previous-server-version: '10.14' 31 | current-server-version: '10.15' 32 | oc-changelog-url: 'https://owncloud.com/changelog/server/' 33 | oc-install-package-url: 'https://download.owncloud.com/server/stable/?sort=time&order=asc' 34 | oc-examples-server-url: 'https://owncloud.install.com/owncloud' 35 | oc-examples-server-ip: '127.0.0.1' 36 | oc-examples-username: 'username' 37 | oc-examples-password: 'password' 38 | oc-complete-name: 'owncloud-complete-latest' 39 | occ-command-example-prefix: 'sudo -u www-data ./occ' 40 | occ-command-example-prefix-no-sudo: 'occ' 41 | php-net-url: 'https://www.php.net' 42 | php-supported-versions-url: 'https://www.php.net/supported-versions.php' 43 | http-status-codes-base-url: 'https://developer.mozilla.org/en-US/docs/Web/HTTP/Status' 44 | std-port-http: '8080' 45 | std-port-memcache: '11211' 46 | std-port-mysql: '3306' 47 | std-port-redis: '6379' 48 | # ocis 49 | # branch versions 50 | latest-ocis-version: '7.1' 51 | previous-ocis-version: '7.0' 52 | # Versions mainly for printing like in docs-main release info and in docs-ocis to define the latest production version. 53 | # Versions in the ocis docs need to be defined in the branch specific docs-ocis/antora.yaml file. 54 | # To do so, change the values in the branch of docs-ocis/antora.yml like service_xxx and compose_xxx. 55 | ocis-actual-version: '7.1.3' 56 | ocis-former-version: '7.0.0' 57 | # Needed in docs-ocis to define which rolling release to print like in the envvars table or in deployment examples 58 | ocis-rolling-version: '7.1.2' 59 | ocis-compiled: '2025-03-30 00:00:00 +0000 UTC' 60 | ocis-downloadpage-url: 'https://download.owncloud.com/ocis/ocis' 61 | # webui 62 | latest-webui-version: 'next' 63 | previous-webui-version: 'next' 64 | # desktop 65 | latest-desktop-version: '5.3' 66 | previous-desktop-version: '5.2' 67 | # ios-app 68 | latest-ios-version: '12.5' 69 | previous-ios-version: '12.4' 70 | # android 71 | latest-android-version: '4.5' 72 | previous-android-version: '4.4' 73 | -------------------------------------------------------------------------------- /overlay/android-chrome-192x192.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/owncloud/docs/08c13d3e438dbe6bd06b7ebab9dd6f215ed41719/overlay/android-chrome-192x192.png -------------------------------------------------------------------------------- /overlay/android-chrome-512x512.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/owncloud/docs/08c13d3e438dbe6bd06b7ebab9dd6f215ed41719/overlay/android-chrome-512x512.png -------------------------------------------------------------------------------- /overlay/apple-touch-icon-120x120.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/owncloud/docs/08c13d3e438dbe6bd06b7ebab9dd6f215ed41719/overlay/apple-touch-icon-120x120.png -------------------------------------------------------------------------------- /overlay/apple-touch-icon-152x152.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/owncloud/docs/08c13d3e438dbe6bd06b7ebab9dd6f215ed41719/overlay/apple-touch-icon-152x152.png -------------------------------------------------------------------------------- /overlay/apple-touch-icon-180x180.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/owncloud/docs/08c13d3e438dbe6bd06b7ebab9dd6f215ed41719/overlay/apple-touch-icon-180x180.png -------------------------------------------------------------------------------- /overlay/apple-touch-icon-60x60.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/owncloud/docs/08c13d3e438dbe6bd06b7ebab9dd6f215ed41719/overlay/apple-touch-icon-60x60.png -------------------------------------------------------------------------------- /overlay/apple-touch-icon-76x76.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/owncloud/docs/08c13d3e438dbe6bd06b7ebab9dd6f215ed41719/overlay/apple-touch-icon-76x76.png -------------------------------------------------------------------------------- /overlay/apple-touch-icon-precomposed.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/owncloud/docs/08c13d3e438dbe6bd06b7ebab9dd6f215ed41719/overlay/apple-touch-icon-precomposed.png -------------------------------------------------------------------------------- /overlay/apple-touch-icon.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/owncloud/docs/08c13d3e438dbe6bd06b7ebab9dd6f215ed41719/overlay/apple-touch-icon.png -------------------------------------------------------------------------------- /overlay/browserconfig.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | #001840 7 | 8 | 9 | 10 | -------------------------------------------------------------------------------- /overlay/favicon-16x16.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/owncloud/docs/08c13d3e438dbe6bd06b7ebab9dd6f215ed41719/overlay/favicon-16x16.png -------------------------------------------------------------------------------- /overlay/favicon-32x32.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/owncloud/docs/08c13d3e438dbe6bd06b7ebab9dd6f215ed41719/overlay/favicon-32x32.png -------------------------------------------------------------------------------- /overlay/favicon.ico: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/owncloud/docs/08c13d3e438dbe6bd06b7ebab9dd6f215ed41719/overlay/favicon.ico -------------------------------------------------------------------------------- /overlay/favicon.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 12 | 13 | 14 | 29 | 30 | -------------------------------------------------------------------------------- /overlay/favicon.txt: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | Note: the apple-touch-icon-precomposed.png is a plain copy of the 11 | apple-touch-icon.png and necessary for devices iOS < 7. 12 | 13 | Note: the favicon.svg is sized to w/h 16x16 and viewBox="0 0 16 16" in the 14 | definition so that we can create more easily the icon for safari below. 15 | 16 | Note: the "safari-pinned-tab.svg" is a special flavour of favicon.svg 17 | as it has replaced white in the bubbles with transparent. This is necessary 18 | for Safari, see 19 | https://developer.apple.com/library/archive/documentation/AppleApplications/Reference/SafariWebContent/pinnedTabs/pinnedTabs.html 20 | -------------------------------------------------------------------------------- /overlay/manifest.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "ownCloud Documentation", 3 | "short_name": "ownCloud Doc", 4 | "description": "The ownCloud Documentation", 5 | "lang": "en", 6 | "dir": "ltr", 7 | "display": "standalone", 8 | "orientation": "any", 9 | "icons": [ 10 | { 11 | "src": "/android-chrome-192x192.png", 12 | "sizes": "192x192", 13 | "type": "image/png" 14 | }, 15 | { 16 | "src": "/android-chrome-512x512.png", 17 | "sizes": "512x512", 18 | "type": "image/png" 19 | } 20 | ], 21 | "theme_color": "#ffffff", 22 | "background_color": "#ffffff" 23 | } 24 | -------------------------------------------------------------------------------- /overlay/mstile-144x144.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/owncloud/docs/08c13d3e438dbe6bd06b7ebab9dd6f215ed41719/overlay/mstile-144x144.png -------------------------------------------------------------------------------- /overlay/mstile-150x150.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/owncloud/docs/08c13d3e438dbe6bd06b7ebab9dd6f215ed41719/overlay/mstile-150x150.png -------------------------------------------------------------------------------- /overlay/mstile-310x150.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/owncloud/docs/08c13d3e438dbe6bd06b7ebab9dd6f215ed41719/overlay/mstile-310x150.png -------------------------------------------------------------------------------- /overlay/mstile-310x310.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/owncloud/docs/08c13d3e438dbe6bd06b7ebab9dd6f215ed41719/overlay/mstile-310x310.png -------------------------------------------------------------------------------- /overlay/mstile-70x70.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/owncloud/docs/08c13d3e438dbe6bd06b7ebab9dd6f215ed41719/overlay/mstile-70x70.png -------------------------------------------------------------------------------- /overlay/opengraph-android.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/owncloud/docs/08c13d3e438dbe6bd06b7ebab9dd6f215ed41719/overlay/opengraph-android.png -------------------------------------------------------------------------------- /overlay/opengraph-branding.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/owncloud/docs/08c13d3e438dbe6bd06b7ebab9dd6f215ed41719/overlay/opengraph-branding.png -------------------------------------------------------------------------------- /overlay/opengraph-default.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/owncloud/docs/08c13d3e438dbe6bd06b7ebab9dd6f215ed41719/overlay/opengraph-default.png -------------------------------------------------------------------------------- /overlay/opengraph-desktop.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/owncloud/docs/08c13d3e438dbe6bd06b7ebab9dd6f215ed41719/overlay/opengraph-desktop.png -------------------------------------------------------------------------------- /overlay/opengraph-docs.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/owncloud/docs/08c13d3e438dbe6bd06b7ebab9dd6f215ed41719/overlay/opengraph-docs.png -------------------------------------------------------------------------------- /overlay/opengraph-ios-app.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/owncloud/docs/08c13d3e438dbe6bd06b7ebab9dd6f215ed41719/overlay/opengraph-ios-app.png -------------------------------------------------------------------------------- /overlay/opengraph-ocis.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/owncloud/docs/08c13d3e438dbe6bd06b7ebab9dd6f215ed41719/overlay/opengraph-ocis.png -------------------------------------------------------------------------------- /overlay/opengraph-server.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/owncloud/docs/08c13d3e438dbe6bd06b7ebab9dd6f215ed41719/overlay/opengraph-server.png -------------------------------------------------------------------------------- /overlay/opengraph-user.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/owncloud/docs/08c13d3e438dbe6bd06b7ebab9dd6f215ed41719/overlay/opengraph-user.png -------------------------------------------------------------------------------- /overlay/opengraph-webui.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/owncloud/docs/08c13d3e438dbe6bd06b7ebab9dd6f215ed41719/overlay/opengraph-webui.png -------------------------------------------------------------------------------- /overlay/robots.txt: -------------------------------------------------------------------------------- 1 | User-agent: * 2 | Sitemap: https://doc.owncloud.com/sitemap.xml 3 | -------------------------------------------------------------------------------- /overlay/safari-pinned-tab.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | -------------------------------------------------------------------------------- /overlay/ui.yml: -------------------------------------------------------------------------------- 1 | static_files: 2 | - android-chrome-192x192.png 3 | - android-chrome-512x512.png 4 | - apple-touch-icon.png 5 | - apple-touch-icon-60x60.png 6 | - apple-touch-icon-76x76.png 7 | - apple-touch-icon-120x120.png 8 | - apple-touch-icon-152x152.png 9 | - apple-touch-icon-180x180.png 10 | - apple-touch-icon-precomposed.png 11 | - browserconfig.xml 12 | - favicon.ico 13 | - favicon.svg 14 | - favicon-16x16.png 15 | - favicon-32x32.png 16 | - manifest.json 17 | - mstile-70x70.png 18 | - mstile-144x144.png 19 | - mstile-150x150.png 20 | - mstile-310x150.png 21 | - mstile-310x310.png 22 | - opengraph-android.png 23 | - opengraph-branding.png 24 | - opengraph-default.png 25 | - opengraph-desktop.png 26 | - opengraph-docs.png 27 | - opengraph-ios-app.png 28 | - opengraph-ocis.png 29 | - opengraph-server.png 30 | - opengraph-user.png 31 | - opengraph-webui.png 32 | - robots.txt 33 | - safari-pinned-tab.svg 34 | -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "private": true, 3 | "name": "owncloud-docs", 4 | "description": "The ownCloud documentation", 5 | "version": "4.0.0", 6 | "license": "AGPL-3.0", 7 | "author": "The ownCloud Team", 8 | "homepage": "https://github.com/owncloud/docs#readme", 9 | "repository": { 10 | "type": "git", 11 | "url": "git+https://github.com/owncloud/docs.git" 12 | }, 13 | "bugs": { 14 | "url": "https://github.com/owncloud/docs/issues" 15 | }, 16 | "contributors": [ 17 | { 18 | "name": "Martin Mattel" 19 | }, 20 | { 21 | "name": "Edith Parzefall" 22 | }, 23 | { 24 | "name": "Phil Davis" 25 | } 26 | ], 27 | "scripts": { 28 | "antora": "antora --stacktrace --cache-dir cache --redirect-facility static --clean --fetch site.yml", 29 | "antora-local": "antora --stacktrace --cache-dir cache --redirect-facility static --clean --fetch --url http://localhost:8080 site.yml", 30 | "antora-staging": "antora --stacktrace --cache-dir cache --redirect-facility static --clean --fetch --url https://doc.staging.owncloud.com site.yml", 31 | "antora-bundle": "antora --stacktrace --cache-dir cache --redirect-facility static --clean --fetch --ui-bundle-url ../docs-ui/build/ui-bundle.zip --url https://doc.staging.owncloud.com site.yml", 32 | "antora-dev-local": "antora --stacktrace --cache-dir cache --redirect-facility static --clean --fetch --url http://localhost:8080 site-dev.yml", 33 | "antora-dev-bundle": "antora --stacktrace --cache-dir cache --redirect-facility static --clean --fetch --ui-bundle-url ../docs-ui/build/ui-bundle.zip --url http://localhost:8080 site-dev.yml", 34 | "serve": "http-server public/ -d -i", 35 | "linkcheck": "broken-link-checker --filter-level 3 --recursive --verbose" 36 | }, 37 | "dependencies": { 38 | "@elastic/elasticsearch": "^7.17.14", 39 | "antora": "^3.1.10", 40 | "asciidoctor": "^3.0.4", 41 | "asciidoctor-kroki": "^0.18.1", 42 | "cheerio": "^1.0.0", 43 | "html-entities": "2.6.0", 44 | "js-yaml": "^4.1.0", 45 | "lodash": "^4.17.21" 46 | }, 47 | "devDependencies": { 48 | "broken-link-checker": "^0.7.8", 49 | "http-server": "^14.1.1" 50 | }, 51 | "keywords": [ 52 | "antora", 53 | "asciidoc", 54 | "documentation", 55 | "owncloud", 56 | "kiteworks" 57 | ] 58 | } 59 | -------------------------------------------------------------------------------- /pdf_web/.gitignore: -------------------------------------------------------------------------------- 1 | !.gitignore 2 | **/** 3 | 4 | # 5 | # include what you want to keep first, reincluding fails 6 | # !.gitignore do not ignore the .gitignore file 7 | # **/** ignore all files and folders starting from the level of .gitignore 8 | 9 | ### the following is only present in case we want to have different rules later on 10 | 11 | ## this directory only pushes pdf files from any locations in this folder 12 | ## 13 | ## only do changes to the files in case you KNOW WHAT YOU ARE DOING !! 14 | 15 | ## ignore everything 16 | #* 17 | 18 | ## but do not ignore files ending with a slash = directories 19 | #!*/ 20 | 21 | ## and do not ignore files anding with ".pdf" 22 | #!*.pdf 23 | 24 | ## and do not ignore the ".gitignore" file 25 | #!.gitignore 26 | 27 | -------------------------------------------------------------------------------- /resources/themes/custom-theme.yml: -------------------------------------------------------------------------------- 1 | font: 2 | catalog: 3 | # Noto Serif supports Latin, Latin-1 Supplement, Latin Extended-A, Greek, Cyrillic, Vietnamese & an assortment of symbols 4 | Noto Serif: 5 | normal: notoserif-regular-subset.ttf 6 | bold: notoserif-bold-subset.ttf 7 | italic: notoserif-italic-subset.ttf 8 | bold_italic: notoserif-bold_italic-subset.ttf 9 | # M+ 1mn supports ASCII and the circled numbers used for conums 10 | M+ 1mn: 11 | normal: mplus1mn-regular-ascii-conums.ttf 12 | bold: mplus1mn-bold-ascii.ttf 13 | italic: mplus1mn-italic-ascii.ttf 14 | bold_italic: mplus1mn-bold_italic-ascii.ttf 15 | # M+ 1p supports Latin, Latin-1 Supplement, Latin Extended, Greek, Cyrillic, Vietnamese, Japanese & an assortment of symbols 16 | # It also provides arrows for ->, <-, => and <= replacements in case these glyphs are missing from font 17 | M+ 1p Fallback: 18 | normal: mplus1p-regular-fallback.ttf 19 | bold: mplus1p-regular-fallback.ttf 20 | italic: mplus1p-regular-fallback.ttf 21 | bold_italic: mplus1p-regular-fallback.ttf 22 | fallbacks: 23 | - M+ 1p Fallback 24 | page: 25 | background_color: ffffff 26 | layout: portrait 27 | margin: [0.5in, 0.67in, 0.67in, 0.67in] 28 | # margin_inner and margin_outer keys are used for recto/verso print margins when media=press 29 | margin_inner: 0.75in 30 | margin_outer: 0.59in 31 | size: A4 32 | base: 33 | align: justify 34 | # color as hex string (leading # is optional) 35 | font_color: 333333 36 | # color as RGB array 37 | #font_color: [51, 51, 51] 38 | # color as CMYK array (approximated) 39 | #font_color: [0, 0, 0, 0.92] 40 | #font_color: [0, 0, 0, 92%] 41 | font_family: Noto Serif 42 | # choose one of these font_size/line_height_length combinations 43 | #font_size: 14 44 | #line_height_length: 20 45 | #font_size: 11.25 46 | #line_height_length: 18 47 | #font_size: 11.2 48 | #line_height_length: 16 49 | font_size: 10.5 50 | #line_height_length: 15 51 | # correct line height for Noto Serif metrics 52 | line_height_length: 12 53 | #font_size: 11.25 54 | #line_height_length: 18 55 | line_height: $base_line_height_length / $base_font_size 56 | font_size_large: round($base_font_size * 1.25) 57 | font_size_small: round($base_font_size * 0.85) 58 | font_size_min: $base_font_size * 0.75 59 | font_style: normal 60 | border_color: eeeeee 61 | border_radius: 4 62 | border_width: 0.5 63 | # FIXME vertical_rhythm is weird; we should think in terms of ems 64 | #vertical_rhythm: $base_line_height_length * 2 / 3 65 | # correct line height for Noto Serif metrics (comes with built-in line height) 66 | vertical_rhythm: $base_line_height_length 67 | horizontal_rhythm: $base_line_height_length 68 | # QUESTION should vertical_spacing be block_spacing instead? 69 | vertical_spacing: $vertical_rhythm 70 | link: 71 | font_color: 428bca 72 | # literal is currently used for inline monospaced in prose and table cells 73 | literal: 74 | font_color: b12146 75 | font_family: M+ 1mn 76 | menu_caret_content: " \u203a " 77 | heading: 78 | align: left 79 | #font_color: 181818 80 | font_color: $base_font_color 81 | font_family: $base_font_family 82 | font_style: bold 83 | # h1 is used for part titles (book doctype only) 84 | h1_font_size: floor($base_font_size * 2.6) 85 | # h2 is used for chapter titles (book doctype only) 86 | h2_font_size: floor($base_font_size * 2.15) 87 | h3_font_size: round($base_font_size * 1.7) 88 | h4_font_size: $base_font_size_large 89 | h5_font_size: $base_font_size 90 | h6_font_size: $base_font_size_small 91 | #line_height: 1.4 92 | # correct line height for Noto Serif metrics (comes with built-in line height) 93 | line_height: 1 94 | margin_top: $vertical_rhythm * 0.4 95 | margin_bottom: $vertical_rhythm * 0.9 96 | title_page: 97 | align: right 98 | logo: 99 | top: 10% 100 | title: 101 | top: 55% 102 | font_size: $heading_h1_font_size 103 | font_color: 999999 104 | line_height: 0.9 105 | subtitle: 106 | font_size: $heading_h3_font_size 107 | font_style: bold_italic 108 | line_height: 1 109 | authors: 110 | margin_top: $base_font_size * 1.25 111 | font_size: $base_font_size_large 112 | font_color: 181818 113 | revision: 114 | margin_top: $base_font_size * 1.25 115 | block: 116 | margin_top: 0 117 | margin_bottom: $vertical_rhythm 118 | caption: 119 | align: left 120 | font_style: italic 121 | # FIXME perhaps set line_height instead of / in addition to margins? 122 | margin_inside: $vertical_rhythm / 3 123 | #margin_inside: $vertical_rhythm / 4 124 | margin_outside: 0 125 | lead: 126 | font_size: $base_font_size_large 127 | line_height: 1.4 128 | abstract: 129 | font_color: 5c6266 130 | font_size: $lead_font_size 131 | line_height: $lead_line_height 132 | font_style: italic 133 | first_line_font_style: bold 134 | admonition: 135 | border_color: $base_border_color 136 | border_width: $base_border_width 137 | padding: [0, $horizontal_rhythm, 0, $horizontal_rhythm] 138 | # icon: 139 | # tip: 140 | # name: fa-lightbulb-o 141 | # stroke_color: 111111 142 | # size: 24 143 | blockquote: 144 | font_color: $base_font_color 145 | font_size: $base_font_size_large 146 | border_color: $base_border_color 147 | border_width: 5 148 | padding: [0, $horizontal_rhythm, $block_margin_bottom * -0.75, $horizontal_rhythm + $blockquote_border_width / 2] 149 | cite_font_size: $base_font_size_small 150 | cite_font_color: 999999 151 | # code is used for source blocks (perhaps change to source or listing?) 152 | code: 153 | font_color: $base_font_color 154 | font_family: $literal_font_family 155 | font_size: ceil($base_font_size) 156 | padding: $code_font_size 157 | line_height: 1.25 158 | background_color: f5f5f5 159 | border_color: cccccc 160 | border_radius: $base_border_radius 161 | border_width: 0.75 162 | conum: 163 | font_family: M+ 1mn 164 | font_color: $literal_font_color 165 | font_size: $base_font_size 166 | line_height: 4 / 3 167 | example: 168 | border_color: $base_border_color 169 | border_radius: $base_border_radius 170 | border_width: 0.75 171 | background_color: transparent 172 | # FIXME reenable margin bottom once margin collapsing is implemented 173 | padding: [$vertical_rhythm, $horizontal_rhythm, 0, $horizontal_rhythm] 174 | image: 175 | align: left 176 | prose: 177 | margin_top: $block_margin_top 178 | margin_bottom: $block_margin_bottom 179 | sidebar: 180 | border_color: $page_background_color 181 | border_radius: $base_border_radius 182 | border_width: $base_border_width 183 | background_color: eeeeee 184 | # FIXME reenable margin bottom once margin collapsing is implemented 185 | padding: [$vertical_rhythm, $vertical_rhythm * 1.25, 0, $vertical_rhythm * 1.25] 186 | title: 187 | align: center 188 | font_color: $heading_font_color 189 | font_family: $heading_font_family 190 | font_size: $heading_h4_font_size 191 | font_style: $heading_font_style 192 | thematic_break: 193 | border_color: $base_border_color 194 | border_style: solid 195 | border_width: $base_border_width 196 | margin_top: $vertical_rhythm * 0.5 197 | margin_bottom: $vertical_rhythm * 1.5 198 | description_list: 199 | term_font_style: italic 200 | term_spacing: $vertical_rhythm / 4 201 | description_indent: $horizontal_rhythm * 1.25 202 | outline_list: 203 | indent: $horizontal_rhythm * 1.5 204 | # NOTE item_spacing applies to list items that do not have complex content 205 | item_spacing: $vertical_rhythm / 2 206 | #marker_font_color: 404040 207 | table: 208 | background_color: $page_background_color 209 | #head_background_color: 210 | #head_font_color: $base_font_color 211 | head_font_style: bold 212 | even_row_background_color: f9f9f9 213 | #odd_row_background_color: 214 | foot_background_color: f0f0f0 215 | border_color: dddddd 216 | border_width: $base_border_width 217 | # HACK accounting for line-height 218 | cell_padding: [3, 3, 6, 3] 219 | toc: 220 | dot_leader_color: dddddd 221 | #dot_leader_content: '. ' 222 | indent: $horizontal_rhythm 223 | line_height: 1.4 224 | # NOTE In addition to footer, header is also supported 225 | footer: 226 | font_size: $base_font_size_small 227 | # NOTE if background_color is set, background and border will span width of page 228 | border_color: dddddd 229 | border_width: 0.25 230 | height: $base_line_height_length * 2.5 231 | line_height: 1 232 | padding: [$base_line_height_length / 2, 1, 0, 1] 233 | vertical_align: top 234 | #image_vertical_align: or 235 | # additional attributes for content: 236 | # * {page-count} 237 | # * {page-number} 238 | # * {document-title} 239 | # * {document-subtitle} 240 | # * {chapter-title} 241 | # * {section-title} 242 | # * {section-or-chapter-title} 243 | recto: 244 | #columns: "<50%,0%,>50%" 245 | right: 246 | content: '{page-number}' 247 | #content: '{section-or-chapter-title} | {page-number}' 248 | #content: '{document-title} | {page-number}' 249 | #center: 250 | # content: '{page-number}' 251 | verso: 252 | #columns: "<50%,0%,>50%" 253 | left: 254 | content: '{page-number}' 255 | #content: '{page-number} | {chapter-title}' 256 | #center: 257 | # content: '{page-number}' 258 | -------------------------------------------------------------------------------- /resources/themes/owncloud-theme.yml: -------------------------------------------------------------------------------- 1 | font: 2 | catalog: 3 | # Noto Serif supports Latin, Latin-1 Supplement, Latin Extended-A, Greek, Cyrillic, Vietnamese & an assortment of symbols 4 | Noto Serif: 5 | normal: notoserif-regular.ttf 6 | bold: notoserif-bold.ttf 7 | italic: notoserif-italic.ttf 8 | bold_italic: notoserif-bold_italic.ttf 9 | # M+ 1mn supports ASCII and the circled numbers used for conums 10 | M+ 1mn: 11 | normal: mplus-1mn-regular.ttf 12 | bold: mplus-1mn-bold.ttf 13 | italic: mplus-1mn-thin.ttf 14 | bold_italic: mplus-1mn-medium.ttf 15 | # M+ 1p supports Latin, Latin-1 Supplement, Latin Extended, Greek, Cyrillic, Vietnamese, Japanese & an assortment of symbols 16 | # It also provides arrows for ->, <-, => and <= replacements in case these glyphs are missing from font 17 | M+ 1p Fallback: 18 | normal: mplus-1p-regular.ttf 19 | bold: mplus-1p-regular.ttf 20 | italic: mplus-1p-regular.ttf 21 | bold_italic: mplus-1p-regular.ttf 22 | Open Sans: 23 | normal: opensans-light.ttf 24 | bold: opensans-bold.ttf 25 | italic: opensans-italic.ttf 26 | bold_italic: opensans-bolditalic.ttf 27 | DejaVu Sans: 28 | normal: dejavu-sans.ttf 29 | bold: dejavu-sans-bold.ttf 30 | italic: dejavu-sans-oblique.ttf 31 | bold_italic: dejavu-sans-boldoblique.ttf 32 | DejaVu Serif: 33 | normal: dejavuserif.ttf 34 | bold: dejavuserif-bold.ttf 35 | italic: dejavuserif-italic.ttf 36 | bold_italic: dejavuserif-bolditalic.ttf 37 | page: 38 | background_color: ffffff 39 | layout: portrait 40 | margin: [0.5in, 0.9in, 0.5in, 0.9in] 41 | # margin_inner and margin_outer keys are used for recto/verso print margins when media=press 42 | margin_inner: 0.75in 43 | margin_outer: 0.59in 44 | size: A4 45 | base: 46 | align: left 47 | font_color: 1c1c1c 48 | font_family: "DejaVu Serif" 49 | font_size: 10.5 50 | line_height_length: 11 51 | line_height: $base_line_height_length / $base_font_size 52 | #line_height: 1 53 | font_size_large: round($base_font_size * 1.25) 54 | font_size_small: round($base_font_size * 0.85) 55 | font_size_min: $base_font_size * 0.75 56 | font_style: normal 57 | border_color: eeeeee 58 | border_radius: 4 59 | border_width: 0.5 60 | # FIXME vertical_rhythm is weird; we should think in terms of ems 61 | #vertical_rhythm: $base_line_height_length * 2 / 3 62 | # correct line height for Noto Serif metrics (comes with built-in line height) 63 | vertical_rhythm: $base_line_height_length 64 | horizontal_rhythm: $base_line_height_length 65 | # QUESTION should vertical_spacing be block_spacing instead? 66 | vertical_spacing: $vertical_rhythm 67 | link: 68 | font_color: 3c7467 69 | # literal is currently used for inline monospaced in prose and table cells 70 | literal: 71 | font_color: b12146 72 | font_family: "DejaVu Sans" 73 | menu_caret_content: " \u203a " 74 | heading: 75 | align: left 76 | #font_color: 181818 77 | font_color: 24475f 78 | font_family: "Open Sans" 79 | font_style: bold 80 | # h1 is used for part titles (book doctype only) 81 | h1: 82 | page_break_after: always 83 | page_break_before: auto 84 | font_size: floor($base_font_size * 2.7) 85 | # h2 is used for chapter titles (book doctype only) 86 | h2_font_size: floor($base_font_size * 2.0) 87 | h3_font_size: round($base_font_size * 1.6) 88 | h4_font_size: $base_font_size_large 89 | h5_font_size: $base_font_size 90 | h6_font_size: $base_font_size_small 91 | #line_height: 1.4 92 | # correct line height for Noto Serif metrics (comes with built-in line height) 93 | line_height: 1 94 | margin_top: $vertical_rhythm * 0.4 95 | margin_bottom: $vertical_rhythm * 0.9 96 | title_page: 97 | align: right 98 | logo: 99 | top: 10% 100 | title: 101 | top: 55% 102 | font_size: floor($base_font_size * 2.14) 103 | font_color: 24475f 104 | font_family: $heading_font_family 105 | font_style: bold 106 | line_height: 0.9 107 | subtitle: 108 | font_size: floor($base_font_size * 1.7) 109 | font_style: bold_italic 110 | font_family: $heading_font_family 111 | line_height: 1 112 | authors: 113 | margin_top: $base_font_size * 1.25 114 | font_size: $base_font_size_large 115 | font_color: 24475f 116 | font_family: $heading_font_family 117 | revision: 118 | margin_top: $base_font_size * 1.25 119 | font_style: bold 120 | font_color: 24475f 121 | block: 122 | margin_top: 0 123 | margin_bottom: $vertical_rhythm 124 | caption: 125 | align: left 126 | font_style: italic 127 | # FIXME perhaps set line_height instead of / in addition to margins? 128 | margin_inside: $vertical_rhythm / 3 129 | #margin_inside: $vertical_rhythm / 4 130 | margin_outside: 0 131 | lead: 132 | font_size: $base_font_size_large 133 | line_height: 1.4 134 | abstract: 135 | font_color: 5c6266 136 | font_size: $lead_font_size 137 | line_height: $lead_line_height 138 | font_style: italic 139 | first_line_font_style: bold 140 | admonition: 141 | border_color: $base_border_color 142 | border_width: $base_border_width 143 | padding: [0, $horizontal_rhythm, 0, $horizontal_rhythm] 144 | # icon: 145 | # tip: 146 | # name: fa-lightbulb-o 147 | # stroke_color: 111111 148 | # size: 24 149 | blockquote: 150 | font_color: $base_font_color 151 | font_size: $base_font_size_large 152 | border_color: $base_border_color 153 | border_width: 5 154 | padding: [0, $horizontal_rhythm, $block_margin_bottom * -0.75, $horizontal_rhythm + $blockquote_border_width / 2] 155 | cite_font_size: $base_font_size_small 156 | cite_font_color: 999999 157 | # code is used for source blocks (perhaps change to source or listing?) 158 | code: 159 | font_color: $base_font_color 160 | font_family: "DejaVu Sans" 161 | font_size: $base_font_size 162 | padding: $code_font_size 163 | line_height: 1.25 164 | background_color: f7f7f7 165 | border_color: efefef 166 | border_radius: $base_border_radius 167 | border_width: 0.75 168 | conum: 169 | font_family: M+ 1mn 170 | font_color: $literal_font_color 171 | font_size: $base_font_size 172 | line_height: 4 / 3 173 | example: 174 | border_color: $base_border_color 175 | border_radius: $base_border_radius 176 | border_width: 0.75 177 | background_color: transparent 178 | # FIXME reenable margin bottom once margin collapsing is implemented 179 | padding: [$vertical_rhythm, $horizontal_rhythm, 0, $horizontal_rhythm] 180 | image: 181 | align: left 182 | prose: 183 | margin_top: $block_margin_top 184 | margin_bottom: $block_margin_bottom 185 | sidebar: 186 | border_color: $page_background_color 187 | border_radius: $base_border_radius 188 | border_width: $base_border_width 189 | background_color: eeeeee 190 | # FIXME reenable margin bottom once margin collapsing is implemented 191 | padding: [$vertical_rhythm, $vertical_rhythm * 1.25, 0, $vertical_rhythm * 1.25] 192 | title: 193 | align: center 194 | font_color: $heading_font_color 195 | font_family: $heading_font_family 196 | font_size: $heading_h4_font_size 197 | font_style: $heading_font_style 198 | thematic_break: 199 | border_color: $base_border_color 200 | border_style: solid 201 | border_width: $base_border_width 202 | margin_top: $vertical_rhythm * 0.5 203 | margin_bottom: $vertical_rhythm * 1.5 204 | description_list: 205 | term_font_style: italic 206 | term_spacing: $vertical_rhythm / 4 207 | description_indent: $horizontal_rhythm * 1.25 208 | outline_list: 209 | indent: $horizontal_rhythm * 1.5 210 | # NOTE item_spacing applies to list items that do not have complex content 211 | item_spacing: $vertical_rhythm / 2 212 | #marker_font_color: 404040 213 | table: 214 | background_color: $page_background_color 215 | head_font_style: bold 216 | head_font_family: Helvetica 217 | even_row_background_color: f9f9f9 218 | foot_background_color: f0f0f0 219 | border_color: dddddd 220 | border_width: $base_border_width 221 | # HACK accounting for line-height 222 | cell_padding: [3, 3, 3, 3] 223 | toc: 224 | dot_leader_color: dddddd 225 | indent: $horizontal_rhythm 226 | line_height: 1.4 227 | font_family: $heading_font_family 228 | # NOTE In addition to footer, header is also supported 229 | footer: 230 | font_size: $base_font_size_small 231 | font_family: Helvetica 232 | font_style: bold 233 | border_color: 1c1c1c 234 | border_width: 0.25 235 | height: $base_line_height_length * 2.5 236 | line_height: 1 237 | padding: [$base_line_height_length / 2, 2, 1, 2] 238 | vertical_align: top 239 | #image_vertical_align: or 240 | # additional attributes for content: 241 | # * {page-count} 242 | # * {page-number} 243 | # * {document-title} 244 | # * {document-subtitle} 245 | # * {chapter-title} 246 | # * {section-title} 247 | # * {section-or-chapter-title} 248 | recto: 249 | #columns: "<50%,0%,>50%" 250 | right: 251 | #content: '{page-number}' 252 | content: '{section-or-chapter-title} | {page-number}' 253 | #content: '{document-title} | {page-number}' 254 | #center: 255 | # content: '{page-number}' 256 | verso: 257 | #columns: "<50%,0%,>50%" 258 | left: 259 | #content: '{page-number}' 260 | content: '{page-number} | {section-or-chapter-title}' 261 | #content: '{page-number} | {chapter-title}' 262 | #center: 263 | # content: '{page-number}' 264 | header: 265 | font_size: $base_font_size_small 266 | font_family: "Noto Serif" 267 | font_style: bold 268 | border_color: 1c1c1c 269 | border_width: 0.25 270 | height: $base_line_height_length * 2.5 271 | line_height: 1 272 | padding: [$base_line_height_length / 2, 1, 2, 1] 273 | vertical_align: bottom 274 | recto: 275 | right: 276 | content: '{document-title}, {appversion}' 277 | #content: '{page-number}' 278 | #content: '{section-or-chapter-title} | {page-number}' 279 | #content: '{document-title} | {page-number}' 280 | verso: 281 | left: 282 | content: '{document-title}, {appversion}' 283 | #content: '{page-number}' 284 | #content: '{page-number} | {chapter-title}' 285 | -------------------------------------------------------------------------------- /site.yml: -------------------------------------------------------------------------------- 1 | site: 2 | title: Documentation for ownCloud (A Kiteworks Company) 3 | url: https://doc.owncloud.com 4 | # the site's landing page resides in the docs_main repository/component 5 | # but it MUST be named ROOT to get a component/version less than the landing page 6 | # this now makes the landing page reside in the url given above WITHOUT getting redirected 7 | # see: https://docs.antora.org/antora/latest/page/start-page/ 8 | # see: https://docs.antora.org/antora/latest/component-name-key/#root-component 9 | start_page: ROOT::index.adoc 10 | 11 | # define all content sources 12 | # note that branches must already exist if changed here 13 | content: 14 | sources: 15 | - url: https://github.com/owncloud/docs-main.git 16 | branches: 17 | - master 18 | - url: https://github.com/owncloud/docs-server.git 19 | branches: 20 | - master 21 | - '10.15' 22 | - '10.14' 23 | - url: https://github.com/owncloud/docs-ocis.git 24 | branches: 25 | - master 26 | - '7.1' 27 | - '7.0' 28 | - url: https://github.com/owncloud/docs-webui.git 29 | branches: 30 | - master 31 | - url: https://github.com/owncloud/docs-client-desktop.git 32 | branches: 33 | - master 34 | - '5.3' 35 | - '5.2' 36 | - url: https://github.com/owncloud/docs-client-ios-app.git 37 | branches: 38 | - master 39 | - '12.5' 40 | - '12.4' 41 | - url: https://github.com/owncloud/docs-client-android.git 42 | branches: 43 | - master 44 | - '4.5' 45 | - '4.4' 46 | 47 | ui: 48 | supplemental_files: overlay 49 | output_dir: assets 50 | bundle: 51 | snapshot: true 52 | url: https://minio.owncloud.com/documentation/ui-bundle.zip 53 | 54 | output: 55 | clean: true 56 | dir: public 57 | 58 | asciidoc: 59 | attributes: 60 | # branch-specific-variables: 'see antora.yml' 61 | # global attributes loaded via antora extension 62 | extensions: 63 | - ./ext-asciidoc/tabs.js 64 | - ./ext-asciidoc/remote-include-processor.js 65 | - asciidoctor-kroki # integrated via npm 66 | 67 | antora: 68 | extensions: 69 | - ./ext-antora/generate-index.js 70 | - ./ext-antora/comp-version.js 71 | - require: ./ext-antora/load-global-site-attributes.js 72 | #attributefile: https://raw.githubusercontent.com/owncloud/docs/refs/heads/master/global-attributes.yml 73 | attributefile: ./global-attributes.yml 74 | enabled: true 75 | # for testing only, prints out attributes used 76 | # use only one or the other, output can be big 77 | #- ./ext-antora/attributes-used-in-site-yml.js 78 | #- ./ext-antora/attributes-used-in-antora-yml.js 79 | --------------------------------------------------------------------------------