Docs Publisher issueshttps://lab.civicrm.org/documentation/docs-publisher/-/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/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/60Automatic publishing for books hosted in GitLab2019-05-21T10:18:44ZSean ColsenAutomatic publishing for books hosted in GitLab*Created by: seanmadsen*
We can automatically publish books when changes are made, but only if the book is hosted on GitHub (and if the owner configures the webhooks correctly). It'd be great to get something like this working for GitLa...*Created by: seanmadsen*
We can automatically publish books when changes are made, but only if the book is hosted on GitHub (and if the owner configures the webhooks correctly). It'd be great to get something like this working for GitLab too, so that we can automatically publish books which are hosted in GitLab.michaelmichaelhttps://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-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/68Build books to a temporary directory before publishing2017-10-09T22:39:38ZSean ColsenBuild books to a temporary directory before publishingBuilding books to a temporary directory before publishing will produce a number of improvements.
The description below is specifically about how using temp dirs will help us avoid broken books. But other benefits come with using temp d...Building books to a temporary directory before publishing will produce a number of improvements.
The description below is specifically about how using temp dirs will help us avoid broken books. But other benefits come with using temp dirs as well, which are described in more detail in the comments below
### Steps to reproduce
1. Set up a book which has a broken internal hyperlink in some page content.
1. When you go into this book (outside of docs-publisher) and run `mkdocs serve`, you should see something like this:
```
WARNING - The page "index.md" contained a hyperlink to "documentation.md" which is not listed in the "pages" configuration.
```
1. Get docs-publisher to publish this book.
1. Because we publish with `--strict` (generally good) the `mkdocs build` process will fail
1. After the failure, the published book will be broken.
### Suggested implementation
1. When publishing a book, first set up a temporary directory in which to build the files
1. Run `mkdocs build`
1. If everything goes according to plan, replace the live directory with the newly built directory
1. If any errors are encountered trash the built directory and report the errors
This ticket is a simplification of #39https://lab.civicrm.org/documentation/docs-publisher/-/issues/67Delete NotifyControllerTest.php2019-05-21T09:59:45ZSean ColsenDelete NotifyControllerTest.php@michaelmcandrew you seem to have created [this file](https://lab.civicrm.org/documentation/docs-publisher/blob/9a8d18b585f2731a8c12cb26a9dc2dbc3f9c4172/src/AppBundle/Tests/Controller/NotifyControllerTest.php) but as far as I can tell it...@michaelmcandrew you seem to have created [this file](https://lab.civicrm.org/documentation/docs-publisher/blob/9a8d18b585f2731a8c12cb26a9dc2dbc3f9c4172/src/AppBundle/Tests/Controller/NotifyControllerTest.php) but as far as I can tell it doesn't do anything.
Can we either:
1. delete it (my preference, since there's really not much there)
1. *or* move it to the `/tests` folder at the root level and add enough code to the file to make it useful.
I'm just trying to do a little housekeeping and this file seemed unnecessary. Perhaps I'm wrong though!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-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/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 2019homotechsualhomotechsual