Documentation issueshttps://lab.civicrm.org/groups/documentation/-/issues2023-07-27T15:48:44Zhttps://lab.civicrm.org/documentation/docs-publisher/-/issues/102Refactor Version and Language handling.2023-07-27T15:48:44ZhomotechsualRefactor Version and Language handling.## What is the proposal?
Our next target version for [`mkdocs-material`](https://squidfunk.github.io/mkdocs-material) is 7.0.0 which brings native language handling to mkdocs-material. We could use this to allow single-repository setups...## What is the proposal?
Our next target version for [`mkdocs-material`](https://squidfunk.github.io/mkdocs-material) is 7.0.0 which brings native language handling to mkdocs-material. We could use this to allow single-repository setups for multi-language documentation books which [has been requested](https://chat.civicrm.org/civicrm/pl/ccwcgpa8u7g63j8udt7gneykgh)
This would result in the following changes in behaviour:
1. All link patterns would change for example from: https://docs.civicrm.org/user/en/latest to https://docs.civicrm.org/user/ (with `en` and any [versions](https://squidfunk.github.io/mkdocs-material/setup/setting-up-versioning/#version-warning) being handled by `mkdocs-material` itself)
2. Any currently multilingual documentation book will need to refactor to organise documentation according to the new structure moving files from `/docs/` to `/docs/<lang>` and centralising into a single repository.
## Why would we do this?
This would shift maintenance burden from `docs-publisher` to `mkdocs-material` and allow for `docs-publisher` agnostic handling of versioning and language handling, allow for all documentation to live alongside code which is a desirable pattern and drastically simplify the `docs-publisher` codebase.
## What changes will actually take place?
Any translated extension book or core book repository will be merged into the main repository for the extension/book and the translation repo will be archived. The structure for the User Guide would look like this in the main user guide repository.
> /docs/en/
> /docs/fr/
> /docs/de/
> /docs/es/
> /docs/ca/
## What do we need to proceed?
Robust discussion of the proposed changes in behaviour and some sense of consensus that this would be desirable. Particular emphasis will be given to the opinions of those who maintain multilingual documentation books or copies of books.
## Questions / concerns answered
Impact of URL changes on SEO/search indexing: *Permanent redirect from old URL styles to new will be handled by `docs-publisher`.*homotechsualhomotechsualhttps://lab.civicrm.org/documentation/docs-publisher/-/issues/101Remove author from Docs Books2022-09-12T05:48:49ZhomotechsualRemove author from Docs Books I'm looking to remove the author line from the docs books at https://docs.civicrm.org (shown below):
![image](/uploads/2ba17953231de19777eb9893c6f19a18/image.png)
It's proven to be entirely superfluous - it adds nothing other than vis... I'm looking to remove the author line from the docs books at https://docs.civicrm.org (shown below):
![image](/uploads/2ba17953231de19777eb9893c6f19a18/image.png)
It's proven to be entirely superfluous - it adds nothing other than visual noise.
Thoughts please!homotechsualhomotechsual2022-08-31https://lab.civicrm.org/documentation/meta/-/issues/23Move "core" documentation repositories to GitLab.2020-04-16T15:08:47ZhomotechsualMove "core" documentation repositories to GitLab.We're about to deploy "Docs Publisher 1907" which includes, amongst other improvements - the ability to handle automated book publishing from GitLab and GitHub.
Coupled with the planned changes to how we attribute partner contributions...We're about to deploy "Docs Publisher 1907" which includes, amongst other improvements - the ability to handle automated book publishing from GitLab and GitHub.
Coupled with the planned changes to how we attribute partner contributions (using /spend on GitLab) it would make a lot of sense to move the GitHub based "Core" book repos from GitHub to GitLab (ref: community/community-engagement/wikis/Tracking-Contributions).
The following repos are within the scope of this issue:
1. [ ] [CiviCRM User Guide - English](https://github.com/civicrm/civicrm-user-guide) move to https://lab.civicrm.org/documentation/docs/user-en.
* [x] Create Repo
* [ ] Move Code
* [ ] Update links/references where possible
* [ ] Update book YAML file in the [Docs Books](https://lab.civicrm.org/documentation/docs-books).
* [ ] Make GitHub a read-only mirror.
2. [ ] [CiviCRM User Guide - Català](https://github.com/babu-cat/civicrm-user-guide-ca) move to https://lab.civicrm.org/documentation/docs/user-cat.
* [ ] Create Repo
* [ ] Move Code
* [ ] Update links/references where possible
* [ ] Update book YAML file in the [Docs Books](https://lab.civicrm.org/documentation/docs-books).
* [ ] Make GitHub a read-only mirror.
3. [ ] [CiviCRM User Guide - Français](https://github.com/civicrm-french/civicrm-user-guide) move to https://lab.civicrm.org/documentation/docs/user-fr.
* [x] Create Repo
* [x] Move Code
* [x] Update links/references where possible
* [x] Update book YAML file in the [Docs Books](https://lab.civicrm.org/documentation/docs-books).
* [ ] Make GitHub a read-only mirror.
4. [ ] [CiviCRM User Guide - Español](https://github.com/ixiam/civicrm-user-guide-spanish) move to https://lab.civicrm.org/documentation/docs/user-es.
* [ ] Create Repo
* [ ] Move Code
* [ ] Update links/references where possible
* [ ] Update book YAML file in the [Docs Books](https://lab.civicrm.org/documentation/docs-books).
* [ ] Make GitHub a read-only mirror.
5. [ ] [CiviCRM SysAdmin Guide - English](https://github.com/civicrm/civicrm-sysadmin-guide) move to https://lab.civicrm.org/documentation/docs/sysadmin.
* [x] Create Repo
* [ ] Move Code
* [ ] Update links/references where possible
* [ ] Update book YAML file in the [Docs Books](https://lab.civicrm.org/documentation/docs-books).
* [ ] Make GitHub a read-only mirror.
6. [ ] [CiviCRM Developer Guide - English](https://github.com/civicrm/civicrm-dev-docs) move to https://lab.civicrm.org/documentation/docs/developer.
* [x] Create Repo
* [ ] Move Code
* [ ] Update links/references where possible
* [ ] Update book YAML file in the [Docs Books](https://lab.civicrm.org/documentation/docs-books).
* [ ] Make GitHub a read-only mirror.
7. [x] [CiviCRM Training Guide - English](https://github.com/civicrm/civicrm-training-guide) move to https://lab.civicrm.org/documentation/docs/training.
* [x] Create Repo
* [x] Move Code
* [x] Update links/references where possible
* [x] Update book YAML file in the [Docs Books](https://lab.civicrm.org/documentation/docs-books).
* [x] Make GitHub a read-only mirror.
If there's anything which you thing should be a "core book" let us know below - otherwise thoughts gratefully appreciated.
This issue would depend on the completion of #22 to free up the "documentation/docs" namespace for sub-projects.https://lab.civicrm.org/documentation/docs-publisher/-/issues/11auto-generate PDF / epup versions2019-07-18T08:55:06ZSean Colsenauto-generate PDF / epup versions*Created by: seanmadsen*
SE has gotten [two](
http://civicrm.stackexchange.com/questions/16700/how-to-download-a-copy-of-the-civicrm-user-and-administrator-guide) separate [questions](http://civicrm.stackexchange.com/questions/10900/ho...*Created by: seanmadsen*
SE has gotten [two](
http://civicrm.stackexchange.com/questions/16700/how-to-download-a-copy-of-the-civicrm-user-and-administrator-guide) separate [questions](http://civicrm.stackexchange.com/questions/10900/how-does-one-download-the-civicrm-4-6-user-guide-in-pdf) recently from people wishing to download the User Guide.
It would be great if the docs system would auto-generate PDF and epub copies of each guide as they are updated, or perhaps nightly.
This feature was also part of the older [to-do list](https://github.com/civicrm/civicrm-docs/tree/638e243c6f4eb06086199e3ea8b529541368f688#to-do) within this repo.
Docs Publisher 2019homotechsualhomotechsualhttps://lab.civicrm.org/documentation/docs-books/-/issues/16SearchKit: define terminology eg SearchSegment2024-01-30T18:03:58ZJoeMurraySearchKit: define terminology eg SearchSegment- [ ] Clarify in SK documentation the page that lists terms and defines them. I think this is just a page per term right now for the most part.
- [ ] Define SearchSegment and its intended use cases https://chat.civicrm.org/civicrm/pl/645...- [ ] Clarify in SK documentation the page that lists terms and defines them. I think this is just a page per term right now for the most part.
- [ ] Define SearchSegment and its intended use cases https://chat.civicrm.org/civicrm/pl/645yg19nqjdsmxot4iwdf7c94yMontreal 2024 sprinthttps://lab.civicrm.org/documentation/docs/user-en/-/issues/465SearchKit: Search button2024-02-29T15:20:11ZJoeMurraySearchKit: Search buttonExplain what happens when clicked (old results disappear, etc.). Encourage progressive development of a Search by clicking Search after each change.Explain what happens when clicked (old results disappear, etc.). Encourage progressive development of a Search by clicking Search after each change.jonwattsjonwatts2023-12-03https://lab.civicrm.org/documentation/docs/user-en/-/issues/462SearchKit: With (optional)/With(required)/Without2024-02-29T16:23:35ZJoeMurraySearchKit: With (optional)/With(required)/WithoutDocument the join options, including Join ConditionsDocument the join options, including Join ConditionsKeith NunnKeith Nunn2023-12-03https://lab.civicrm.org/documentation/docs/installation/-/issues/19Update to Drupal 10 on Drupal Installation Guide (or remove 9?)2023-11-07T10:11:32ZresgaUpdate to Drupal 10 on Drupal Installation Guide (or remove 9?)Drupal 9 reaches End Of Life November 2023, [How long will Drupal 9 be supported?](https://www.drupal.org/docs/understanding-drupal/drupal-9-release-date-and-what-it-means/how-long-will-drupal-9-be-supported)
Perhaps the section at the ...Drupal 9 reaches End Of Life November 2023, [How long will Drupal 9 be supported?](https://www.drupal.org/docs/understanding-drupal/drupal-9-release-date-and-what-it-means/how-long-will-drupal-9-be-supported)
Perhaps the section at the top for the latest Drupal release (Drupal 10+) could be updated to just use "Drupal" on the Drupal Installation Guide page? https://docs.civicrm.org/installation/en/latest/drupal/
At a minimum, "Drupal 9" should be updated to "Drupal 10".https://lab.civicrm.org/documentation/docs/installation/-/issues/13Can't install CiviCRM in Drupal 9 with Composer if Drush is installed2022-11-18T11:03:02ZresgaCan't install CiviCRM in Drupal 9 with Composer if Drush is installedOne of the first things I do when starting a new Drupal 9 site, is adding Drush with Composer to be able to install Drupal.
Following the very detailed and thorough documentation page [Install CiviCRM on Drupal 8/9](https://docs.civicrm...One of the first things I do when starting a new Drupal 9 site, is adding Drush with Composer to be able to install Drupal.
Following the very detailed and thorough documentation page [Install CiviCRM on Drupal 8/9](https://docs.civicrm.org/installation/en/latest/drupal8/), I get a "Your requirements could not be resolved" error:
```
$ composer create-project drupal/recommended-project
$ cd recommended-project
$ lando init --source cwd --recipe drupal9 --webroot web --name drupal9
$ lando start
$ lando composer require drush/drush
$ lando composer config extra.enable-patching true
$ lando composer config minimum-stability dev
$ lando composer require civicrm/civicrm-{core,packages,drupal-8}
Using version ^5.44 for civicrm/civicrm-core
Using version ^5.44 for civicrm/civicrm-packages
Using version ^5.44 for civicrm/civicrm-drupal-8
./composer.json has been updated
Running composer update civicrm/civicrm-core civicrm/civicrm-packages civicrm/civicrm-drupal-8
Loading composer repositories with package information
Updating dependencies
Your requirements could not be resolved to an installable set of packages.
Problem 1
- civicrm/civicrm-core[5.44.0, ..., 5.45.x-dev] require symfony/finder ~3.0 || ~4.4 -> found symfony/finder[v3.0.0-BETA1, ..., 3.4.x-dev, v4.4.0-BETA1, ..., 4.4.x-dev] but the package is fixed to v5.4.0 (lock file version) by a partial update and that version does not match. Make sure you list it as an argument for the update command.
- Root composer.json requires civicrm/civicrm-core ^5.44 -> satisfiable by civicrm/civicrm-core[5.44.0, 5.44.x-dev, 5.45.x-dev].
Use the option --with-all-dependencies (-W) to allow upgrades, downgrades and removals for packages currently locked to specific versions.
Installation failed, reverting ./composer.json and ./composer.lock to their original content.
```
If I remove Drush with `lando composer remove drush/drush` and run the command again, CiviCRM is installed as expected. Also, if I add Drush after an older CiviCRM version has been installed (for example `5.42`) I can still update to the latest version, `5.44`. So it seems like Drush locks some version constraints too tightly, if it is installed first.https://lab.civicrm.org/documentation/docs/user-en/-/issues/455Standalone Profile form documentation out-of-date2022-01-14T18:53:47ZSaltStandalone Profile form documentation out-of-dateThe documentation for creating a standalone form from a Profile suggests that there is a `HTML Form Snippet` option that does not appear in my installation (Drupal 8 and CiviCRM 5.38.1). I am not finding any other way to accomplish this ...The documentation for creating a standalone form from a Profile suggests that there is a `HTML Form Snippet` option that does not appear in my installation (Drupal 8 and CiviCRM 5.38.1). I am not finding any other way to accomplish this without using Webforms (which I'm trying to avoid due to past headaches). Would appreciate updated documentation!https://lab.civicrm.org/documentation/docs/sysadmin/-/issues/280Provide technical guidance on common needed workarounds for deduping2021-03-31T06:25:35ZJoeMurrayProvide technical guidance on common needed workarounds for dedupingMedium sized sites of 10k - 50k contacts not uncommonly run into timeouts and similar problems when trying to use dedupe rules. It would be helpful to indicate in the documentation common workarounds, tuning parameters, etc.
For example...Medium sized sites of 10k - 50k contacts not uncommonly run into timeouts and similar problems when trying to use dedupe rules. It would be helpful to indicate in the documentation common workarounds, tuning parameters, etc.
For example, on the Dedupe stuff I think some heuristic rules of thumb for how to tune a site so that one can tune deduping parameters in case of timeouts would be appropriate. So, up PHP max timeout. Increase your RAM. In a db with 10k contact using first name and last name and 60s, choose a group no bigger than XXX contacts.... This is a very common problem.https://lab.civicrm.org/documentation/docs/sysadmin/-/issues/274Create documentation on the different admin themes available2020-11-13T16:03:28ZwmortadaCreate documentation on the different admin themes availableWe now have a number of different admin themes available but this is rather hidden and many users are unaware that there is even an option to change theme. I think it would be good to make this more visible and suggest that we add a page...We now have a number of different admin themes available but this is rather hidden and many users are unaware that there is even an option to change theme. I think it would be good to make this more visible and suggest that we add a page to the Sysadmin guide that covers this.
I would suggest that it covers the following themes as a minimum:
* [Shoreditch](https://civicrm.org/extensions/shoreditch)
* [Finsbury Park](https://civicrm.org/extensions/finsbury-park-cross-cms-admin-theme)
* [Haystack](https://lab.civicrm.org/extensions/haystacktheme)
* [Aah](https://github.com/artfulrobot/aah)
There is some discussion about themes on [this page](https://docs.civicrm.org/sysadmin/en/latest/customize/theme/) but it doesn't mention the above other than Shoreditch and is focussed more on the technicalities of creating a theme rather than installing an existing theme.
More details about themes: https://lab.civicrm.org/dev/user-interfacehttps://lab.civicrm.org/documentation/docs/installation/-/issues/4D8/D9: Improve recommended l10n process2022-10-24T15:04:19ZtottenD8/D9: Improve recommended l10n process(Prompted by the discussion in https://lab.civicrm.org/documentation/docs/sysadmin/-/merge_requests/274)
On the D8/D9 install docs, there are red boxes and the workflow is awkward (e.g. manually re-download and sync files after every up...(Prompted by the discussion in https://lab.civicrm.org/documentation/docs/sysadmin/-/merge_requests/274)
On the D8/D9 install docs, there are red boxes and the workflow is awkward (e.g. manually re-download and sync files after every upgrade?!).
Unorganized braindumps:
(1) A slightly better workflow (which doesn't require patches or manual reinstalls) is to put this in the top-level `composer.json`:
```javascript
"extra": {
"downloads": {
"civi-l10n": {
"path": "vendor/civicrm/civicrm-core/l10n",
"url": "https://download.civicrm.org/civicrm-l10n-core/archives/civicrm-l10n-daily.tar.gz"
}
}
}
```
The only problem... it may cache the daily snapshot indefinitely. I guess you could add a nonce to the URL.
I almost did this for `civicrm_download_composer_d8()` but wasn't sure how to make that change in `composer.json` via bash. It'd be prettier with a CLI one-liner (`composer require foo...` or `composer download foo...`)
(2) Using the `civicrm-X.Y.Z-l10n.tar.gz` would require patches somewhere b/c the paths don't match-up right.
(3) The steps about sync'ing SQL files aren't needed. With civicrm-setup and CLI usage, it gets translations direct from `l10n/**.mo` files. (There are other use-cases which hit those SQL files - but if you use any of the current documented installers for Civi-D8/D9, they're not needed.)
(4) If there were an identifiable package (`composer require civicrm/l10n`):
* Then we could update `civicrm-asset-plugin` to wire it up. (To wit: if `civicrm/l10n` is installed, then `vendor/composer/autoload_civicrm_asset.php` could set `$civicrm_paths['civicrm.l10n']...`. Same as it does for `civicrm.packages`)
* Publishing a `civicrm/l10n` package from `lab.civicrm.org` would work - but may download slow per https://github.com/composer/packagist/issues/1126. But if the same were on Github, it should perform work alright.https://lab.civicrm.org/documentation/meta/-/issues/30CMS Specific Documentation books2019-11-13T14:20:31ZhomotechsualCMS Specific Documentation booksDocumenting CMS specific CiviCRM stuff.Documenting CMS specific CiviCRM stuff.https://lab.civicrm.org/documentation/meta/-/issues/14Explore technologies for generating screenshots from machine-readable specs2018-05-26T22:48:15ZSean ColsenExplore technologies for generating screenshots from machine-readable specsReaders love screenshots. Especially in the User Guide, I think they add quite a lot. But they're hard to maintain. A while back I heard somewhere about a tool which would allow documentation writers to specify how a screenshot should be...Readers love screenshots. Especially in the User Guide, I think they add quite a lot. But they're hard to maintain. A while back I heard somewhere about a tool which would allow documentation writers to specify how a screenshot should be taken in an application. Conceivably, with a tool like this, screenshots would:
* look more consistent
* automatically display the application in the same language as the guide
* be easy to update en masse to follow stylistic application changes (e.g. Shoreditch)
This sounds great, but maybe too good to be true. I can also imagine it being quite hard to use a tool like this. I'm curious though.
I think it could be neat to research this some more and see what tools are out there and how easy it would be for us to adopt them.https://lab.civicrm.org/documentation/docs-publisher/-/issues/66Custom style for external hyperlinks to indicate to the reader that they are ...2021-09-27T11:21:42ZSean ColsenCustom style for external hyperlinks to indicate to the reader that they are externalWhen a hyperlink in a book points to a URL outside of that book, it would be nice if the hyperlink offered some visual style (e.g. icon) to indicate that it's an external link.
Similar to #61When a hyperlink in a book points to a URL outside of that book, it would be nice if the hyperlink offered some visual style (e.g. icon) to indicate that it's an external link.
Similar to #61homotechsualhomotechsualhttps://lab.civicrm.org/documentation/docs/user-en/-/issues/481SearchKit: Import/Export2024-02-29T21:30:37ZKeith NunnSearchKit: Import/ExportDocument the use of the import and export functionality to allow moving and sharing saved searches.Document the use of the import and export functionality to allow moving and sharing saved searches.Keith NunnKeith Nunnhttps://lab.civicrm.org/documentation/docs/user-en/-/issues/480Search: Search Result Actions2024-02-29T20:08:16ZgenadellettSearch: Search Result ActionsActions available from search results are consistent across CiviCRM. This is for developing documentation that explains the purpose and function of each action. This was born out of enhancing documentation for SearchKit actions and recog...Actions available from search results are consistent across CiviCRM. This is for developing documentation that explains the purpose and function of each action. This was born out of enhancing documentation for SearchKit actions and recognizing they are intentionally consistent with actions available elsewhere in the system.genadellettgenadelletthttps://lab.civicrm.org/documentation/docs/user-en/-/issues/479FormBuilder: Permissions Overview2024-02-29T16:00:27ZJoeMurrayFormBuilder: Permissions OverviewThere are fields that define Permission in various places in FormBuilder. This page will explain how they all relate to each other, and provide advice on a recommended "default" standard approach for some types of FormBuilders.There are fields that define Permission in various places in FormBuilder. This page will explain how they all relate to each other, and provide advice on a recommended "default" standard approach for some types of FormBuilders.NadaillacNadaillachttps://lab.civicrm.org/documentation/docs/user-en/-/issues/478FormBuilder: Overview2024-02-29T16:02:36ZJoeMurrayFormBuilder: OverviewPage providing an image at top labelling each section of the FormBuilder page, and describing at a high level what it does/is for. The standard terminology for different parts of page will be as follows:
Call the left: Palette
Call the r...Page providing an image at top labelling each section of the FormBuilder page, and describing at a high level what it does/is for. The standard terminology for different parts of page will be as follows:
Call the left: Palette
Call the right: Canvas
On the left, one adds entities.guyiacguyiac