Docs Publisher issueshttps://lab.civicrm.org/documentation/docs-publisher/-/issues2023-03-31T12:56:00Zhttps://lab.civicrm.org/documentation/docs-publisher/-/issues/103Documentation contains discriminatory example2023-03-31T12:56:00Zkatharina.uDocumentation contains discriminatory exampleOn the following documentation page, there is an example for the API Call getoptions that I consider discriminatory.
https://docs.civicrm.org/dev/en/latest/api/v3/actions/
![Screenshot_2023-03-31_10-38-31](/uploads/e4f4ab2e15031353b48dd8...On the following documentation page, there is an example for the API Call getoptions that I consider discriminatory.
https://docs.civicrm.org/dev/en/latest/api/v3/actions/
![Screenshot_2023-03-31_10-38-31](/uploads/e4f4ab2e15031353b48dd8fc3d4d07f9/Screenshot_2023-03-31_10-38-31.png)
"Transgender" is not a 3rd gender next to "male" and "female". Instead, transgender people _**are**_ either male, female, or non-binary. More information as to why this is hurtful for trans people can be easily researched online.
I am implementing CiviCRM for an organisation fighting discrimination, including gender discrimination.
So I would be very glad if you could correct this mistake / exchange the example.
I propose the following:
array(
1 => 'Female',
2 => 'Male',
3 => 'Non-binary'
)https://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/docs-publisher/-/issues/100Docs falling off organic search results2022-05-25T16:34:56Zjoshjosh@civicrm.orgDocs falling off organic search resultsI've noticed in the past several months that "docs" is appearing less and less on SERPs and, when it does, it's often not on page one. This is inconsistent with past experiences where "docs" often ranked within the top 3 positions on org...I've noticed in the past several months that "docs" is appearing less and less on SERPs and, when it does, it's often not on page one. This is inconsistent with past experiences where "docs" often ranked within the top 3 positions on organic search.
![16-mo-performance](/uploads/9bc76a5172a4006d73c7ac84c283fb8b/16-mo-performance.png)
A review of potential issues using Google Search Console indicates an increasing number of URLs marked as "noindex". A list of current URLs (365 as of today) flagged in this manner [is here](https://docs.google.com/spreadsheets/d/1fcn433yev3OF2-yuAgoF5zugch4AJ5qUKIbD1fHSpJ4/edit?usp=sharing).
Originally, I thought this was specific to certain guides as I've seen a higher number of error URLs under "user" docs than under "dev", however it appears to be a bit more random than I initially thought.
I believe the cause is related to the canonical url declaration combined with a redirect. Google states:
>>>
Excluded: The page is not indexed, but we think that was your intention. (For example, you might have deliberately excluded it by a noindex directive, or it might be a duplicate of a canonical page that we've already indexed on your site.)
>>>
As an example:
1. https://docs.civicrm.org/dev/en/latest/api/v4/custom-data/
1. The current "live" URL.
2. Declared canonical: https://docs.civicrm.org/dev/en/stable/api/v4/custom-data/
3. Google states that this page is not indexed and cites the "[Alternate page with proper canonical tag](https://support.google.com/webmasters/answer/7440203#duplicate_page_with_proper_canonical_tag)".
2. https://docs.civicrm.org/dev/en/stable/api/v4/custom-data/
1. Declared canonical URL is https://docs.civicrm.org/dev/en/stable/api/v4/custom-data/
2. Redirects to https://docs.civicrm.org/dev/en/latest/api/v4/custom-data/
3. Errors with: No: 'noindex' detected in 'X-Robots-Tag' http header (image below)
![url-error](/uploads/6970a72bc5d0ee1897ba430caf7c3782/url-error.png)
I'm not sure if this is correct, however it seems like for pages that are erroring, the issue is declaring a canonical URL that is flagged as "noindex" and that redirects back to the current page.
I believe the proper fix would be to mark the current URL as the user declared canonical (ensure that it is 'indexable', which it seems to be) and maintain the expired URLs as "noindex" as redirects to the current URL.homotechsualhomotechsual2022-04-29https://lab.civicrm.org/documentation/docs-publisher/-/issues/99Publishing no longer working2022-02-09T17:14:27ZjensschuppePublishing no longer workingIs there any reason for why https://docs.civicrm.org/admin/publish/civioffice no longer publishes the current docs of this extension anymore and throws a 500 Server Error instead? Also, automatic publishing doesn't work either via a GitH...Is there any reason for why https://docs.civicrm.org/admin/publish/civioffice no longer publishes the current docs of this extension anymore and throws a 500 Server Error instead? Also, automatic publishing doesn't work either via a GitHub webhook.
I can't find any errors in the MKDocs configuration file or the documents themselves.https://lab.civicrm.org/documentation/docs-publisher/-/issues/98Searching matches partial but not complete word in some cases2021-09-27T08:07:27ZRichSearching matches partial but not complete word in some casesLove the new docs homepage design, well done!
But there's a weirdness. There's an extension called *Pelf*. If I enter `pel` it comes up, but if I type `pelf` it does not.
![Peek_2021-09-27_08-27](/uploads/d33a32031269979aafd50aefbd1a37...Love the new docs homepage design, well done!
But there's a weirdness. There's an extension called *Pelf*. If I enter `pel` it comes up, but if I type `pelf` it does not.
![Peek_2021-09-27_08-27](/uploads/d33a32031269979aafd50aefbd1a3724/Peek_2021-09-27_08-27.gif)
Not sure if this is extension specific - it does not seem to happen on every extension, but Pelf and Deduper are two examples.https://lab.civicrm.org/documentation/docs-publisher/-/issues/97Fix google listing2021-09-27T11:19:36ZStoobFix google listingAlthough I don't believe this is an English specific Doc issue I don't know where else to put it.
As of February 9, google "civicrm documentation" and although we are the top listing this **No information is available for this page.** i...Although I don't believe this is an English specific Doc issue I don't know where else to put it.
As of February 9, google "civicrm documentation" and although we are the top listing this **No information is available for this page.** is displayed/
![co](/uploads/9d9c8dcf14608ad45ee37cd09b4178aa/co.png)
Clicking "learn more" in Google brings you to this information page. https://support.google.com/webmasters/answer/7489871?hl=en I don't know why google feels this way. My guess is that it is a meta setting in the Doc website or on the server.https://lab.civicrm.org/documentation/docs-publisher/-/issues/96Overhaul the docs "front page".2021-09-27T08:10:11ZhomotechsualOverhaul the docs "front page".Our current list-y approach to the content on docs.civicrm.org works but it's getting less useful as we get more and more docs books. I'd like to open the discussion around what we want from that page and how it should look at the same t...Our current list-y approach to the content on docs.civicrm.org works but it's getting less useful as we get more and more docs books. I'd like to open the discussion around what we want from that page and how it should look at the same time as converting it to use the material design aesthetic used in the docs books rather than it's current Bootstrap 3 CSS.
My current thoughts are to switch to presenting the books as "[cards](https://material.io/components/cards)" rather than a list, allowing better control/presentation on Mobile (currently that page is almost unusable on mobile and Google's search console is flagging this as a major issue.
I'm interested in discussion and more ideas - I'm looking to get this done by the second week in May at the latest - I'm planning to prepare some kind of living "demo" in the next day or two!
The most recent preview is here: https://cdn.preview.wales/dp-home/search2/homotechsualhomotechsual2020-05-17https://lab.civicrm.org/documentation/docs-publisher/-/issues/95Implement cookie consent on docs.civicrm.org2021-09-27T11:18:46ZhomotechsualImplement cookie consent on docs.civicrm.orgdocs.civicrm.org / docs-publisher will need to handle cookie consent for GDPR/AVR compliance.
The easiest implementation of this is going to be via https://github.com/ConnectHolland/cookie-consent-bundle.docs.civicrm.org / docs-publisher will need to handle cookie consent for GDPR/AVR compliance.
The easiest implementation of this is going to be via https://github.com/ConnectHolland/cookie-consent-bundle.homotechsualhomotechsual2020-04-30https://lab.civicrm.org/documentation/docs-publisher/-/issues/94All doc links are broken2020-04-11T13:55:18ZdschaferAll doc links are brokenLinks to specific documentation on https://docs.civicrm.org/ all return 404.
Actually all but user docs.Links to specific documentation on https://docs.civicrm.org/ all return 404.
Actually all but user docs.https://lab.civicrm.org/documentation/docs-publisher/-/issues/93Make developer docs more accessible to new Civi developers2019-10-07T10:01:05ZgibsonoliverMake developer docs more accessible to new Civi developershttps://lab.civicrm.org/documentation/docs-publisher/-/issues/92Improve documentation of APIs2019-10-07T09:38:45ZgibsonoliverImprove documentation of APIshttps://lab.civicrm.org/documentation/docs-publisher/-/issues/91Move developer training guide from wiki to docs2019-10-07T10:03:11ZgibsonoliverMove developer training guide from wiki to docshttps://lab.civicrm.org/documentation/docs-publisher/-/issues/90Notification emails don't have DKIM signature2020-03-09T15:39:03ZDaveDNotification emails don't have DKIM signatureI'm only mentioning it since there was a recent push to get all the other civicrm emails signed.
The notification went to my spam but I think that was because coincidentally my email provider had a temp DNS lookup fail so it also couldn...I'm only mentioning it since there was a recent push to get all the other civicrm emails signed.
The notification went to my spam but I think that was because coincidentally my email provider had a temp DNS lookup fail so it also couldn't check SPF.https://lab.civicrm.org/documentation/docs-publisher/-/issues/89Install google analytics2020-04-11T14:39:19Zjoshjosh@civicrm.orgInstall google analyticsWe're currently only tracking the property associated with civicrm.org and would like to see user behavior for docs.civicrm.org. Tracking data below:
```
<!-- Global site tag (gtag.js) - Google Analytics -->
<script async src="https://w...We're currently only tracking the property associated with civicrm.org and would like to see user behavior for docs.civicrm.org. Tracking data below:
```
<!-- Global site tag (gtag.js) - Google Analytics -->
<script async src="https://www.googletagmanager.com/gtag/js?id=UA-1370005-4"></script>
<script>
window.dataLayer = window.dataLayer || [];
function gtag(){dataLayer.push(arguments);}
gtag('js', new Date());
gtag('config', 'UA-1370005-4');
</script>
```Docs Publisher 2019homotechsualhomotechsualhttps://lab.civicrm.org/documentation/docs-publisher/-/issues/88Live "What is CiviCRM?" doesn't list Backdrop, but Github does list Backdrop2019-05-16T16:18:09ZCM ToolanLive "What is CiviCRM?" doesn't list Backdrop, but Github does list BackdropNot 100% sure if this is the right place, but there seems to be an odd difference between what's live on the docs site and the GitHub repository. GitHub lists all four possible CMS choices, but the live site is missing Backdrop.
https:/...Not 100% sure if this is the right place, but there seems to be an odd difference between what's live on the docs site and the GitHub repository. GitHub lists all four possible CMS choices, but the live site is missing Backdrop.
https://docs.civicrm.org/user/en/latest/introduction/what-is-civicrm/
Live:
![Screen_Shot_2019-05-09_at_21.49.33](/uploads/02b3a138d9f224b4407fe230477b5303/Screen_Shot_2019-05-09_at_21.49.33.png)
GitHub:
https://github.com/civicrm/civicrm-user-guide/blob/master/docs/introduction/what-is-civicrm.md
![Screen_Shot_2019-05-09_at_21.49.58](/uploads/99a6871699da692db44d0ff110639834/Screen_Shot_2019-05-09_at_21.49.58.png)https://lab.civicrm.org/documentation/docs-publisher/-/issues/87Documentation: Error 500 returned for bad addresses (should be 404)2020-04-26T20:34:22ZAllenShawDocumentation: Error 500 returned for bad addresses (should be 404)(Meta: not sure where else to file this issue; please direct me to a more appropriate tracker if one exists.)
Steps to reproduce:
1. Visit a nonexistent url under docs.civicrm.org, e.g. for a project that has no documentation there, e.g...(Meta: not sure where else to file this issue; please direct me to a more appropriate tracker if one exists.)
Steps to reproduce:
1. Visit a nonexistent url under docs.civicrm.org, e.g. for a project that has no documentation there, e.g.
https://docs.civicrm.org/foo/ or https://docs.civicrm.org/foo/en/latest/
2. Observe a Error 500 message.
This really seems like it should be a 404 error: I was looking for a resource that's not there.Barcelona Sprinthttps://lab.civicrm.org/documentation/docs-publisher/-/issues/86Live site should display specific build errors when manually publishing2021-09-27T11:19:52ZSean ColsenLive site should display specific build errors when manually publishingIf you manually publish a book on the live site, and the publishing system encounters build errors (e.g. due to incorrect syntax in `mkdocs.yml`, currently you'll see a generic error 500 screen. Instead, you should see a screen which dis...If you manually publish a book on the live site, and the publishing system encounters build errors (e.g. due to incorrect syntax in `mkdocs.yml`, currently you'll see a generic error 500 screen. Instead, you should see a screen which displays the specific error, to aid troubleshooting.https://lab.civicrm.org/documentation/docs-publisher/-/issues/85Peg pip packages to specific versions in the Dockerfile2018-02-26T01:04:29ZSean ColsenPeg pip packages to specific versions in the DockerfileThe Dockerfile within this project installs some packages with pip. We should specify versions for those packages, and those versions should agree with what's installed on the live server.
Related: #84The Dockerfile within this project installs some packages with pip. We should specify versions for those packages, and those versions should agree with what's installed on the live server.
Related: #84https://lab.civicrm.org/documentation/docs-publisher/-/issues/84Upgrade to MkDocs 0.172018-02-26T01:03:17ZSean ColsenUpgrade to MkDocs 0.17On the live server, we are currently running MkDocs 0.16.1.
As of Oct, 2017, [MkDocs 0.17](http://www.mkdocs.org/about/release-notes/#version-0170-2017-10-19) is out. Unfortunately, it has some breaking changes with 0.16. The only motiv...On the live server, we are currently running MkDocs 0.16.1.
As of Oct, 2017, [MkDocs 0.17](http://www.mkdocs.org/about/release-notes/#version-0170-2017-10-19) is out. Unfortunately, it has some breaking changes with 0.16. The only motivation to upgrade (as far as I can tell) is just to keep up with things so that we don't fall too far behind. Currently, trying to publish a book with docs-publisher on a system that has MkDocs 0.17.0+ results in the following error:
> Build errors encountered. Book not published. Build error: 'MkDocs was unable to build the book. MkDocs command output: WARNING - Config value: 'theme_dir'. Warning: The configuration option {0} has been deprecated and will be removed in a future release of MkDocs.
WARNING - Config value: 'site_favicon'. Warning: Unrecognised configuration name: site_favicon Aborted with 2 Configuration Warnings in 'strict' mode!
I havnen't gotten too deep into this yet. Just deep enough to predict that it's going to be a bit of a project.