Docs Publisher issueshttps://lab.civicrm.org/documentation/docs-publisher/-/issues2020-04-26T20:34:22Zhttps://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/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/65Add 1px Boarder for Images2021-09-27T11:21:55ZskesslerAdd 1px Boarder for ImagesI would like to see a 1px border added to images in the guides. I think this makes it clearer to see and understand the screenshots.I would like to see a 1px border added to images in the guides. I think this makes it clearer to see and understand the screenshots.Docs Publisher 2019homotechsualhomotechsualhttps://lab.civicrm.org/documentation/docs-publisher/-/issues/61Open external links in a new tab/window.2019-05-21T10:20:19ZSean ColsenOpen external links in a new tab/window.*Created by: RandyTobias*
Personally speaking, I really hate to be directed away from a site or guide when I am following a link. I'd like to have external links open in a new tab (normally with target=_blank"). I know markdown does not...*Created by: RandyTobias*
Personally speaking, I really hate to be directed away from a site or guide when I am following a link. I'd like to have external links open in a new tab (normally with target=_blank"). I know markdown does not specifically support this behavior, so it was suggested that if people find this to be a worthwhile change, we could use JS to accomplish this task on a global scale.
If desired, this could be accomplished with:
```JS
$( document ).ready(function() {
Array.from( document.querySelectorAll( 'a' ) ).forEach( a => {
a.classList.add( location.hostname === a.hostname || !a.hostname.length ? 'local' : 'external' );
});
$('a.external').each(function(){
$(this).attr('target','_blank');
});
})
```Docs Publisher 2019homotechsualhomotechsualhttps://lab.civicrm.org/documentation/docs-publisher/-/issues/59When acting on GitHub webhooks, only publish if docs content was modified2019-05-21T10:19:35ZSean ColsenWhen acting on GitHub webhooks, only publish if docs content was modified*Created by: seanmadsen*
Now that we have books being published from repos with actual code (in addition to just docs) I think it'd be nice to avoid the server load (and unnecessary notification emails) of re-publishing books when non-d...*Created by: seanmadsen*
Now that we have books being published from repos with actual code (in addition to just docs) I think it'd be nice to avoid the server load (and unnecessary notification emails) of re-publishing books when non-docs changes are made to the repo. For example, if an extension's maintainer makes a code change to their extension, civicrm-docs will currently re-publish the book and send a notification email every time. We could check the paths modified and publish only if we see `/docs` or `/mkdocs.yml`Docs Publisher 2019homotechsualhomotechsualhttps://lab.civicrm.org/documentation/docs-publisher/-/issues/58Allow aliases for book slugs2019-05-21T10:17:41ZSean ColsenAllow aliases for book slugs*Created by: seanmadsen*
It'd be nice if, in a book's yaml config, we could specify aliases for the book slug which would redirect to the book's correct URL if requested. For example, we have a book with the slug `volunteer`. I'd be nic...*Created by: seanmadsen*
It'd be nice if, in a book's yaml config, we could specify aliases for the book slug which would redirect to the book's correct URL if requested. For example, we have a book with the slug `volunteer`. I'd be nice if we could also reach the docs (through a redirect) by requesting URLs with `civivolunter`. This would make it safer to re-name booksDocs Publisher 2019homotechsualhomotechsualhttps://lab.civicrm.org/documentation/docs-publisher/-/issues/53Get details for email notifications from git repo instead of POST request2019-05-21T10:18:15ZSean ColsenGet details for email notifications from git repo instead of POST request*Created by: seanmadsen*
When a book is updated, GitHub sends a webhook POST request to the app. The app then uses data from that request to (1) publish a specific book if necessary, and (2) send notification emails. We should consider ...*Created by: seanmadsen*
When a book is updated, GitHub sends a webhook POST request to the app. The app then uses data from that request to (1) publish a specific book if necessary, and (2) send notification emails. We should consider the request as untrusted data. Therefor for step 2, we should not use data from the request. Instead, we should validate the `before` and `after` refs from the request and use them to inspect the git repo locally and glean whatever info (e.g. email addresses, commit messages, etc.) is necessary for sending this notification email.Docs Publisher 2019homotechsualhomotechsualhttps://lab.civicrm.org/documentation/docs-publisher/-/issues/35Restrict web crawler bots to crawl only one branch per book?2019-05-21T10:12:45ZSean ColsenRestrict web crawler bots to crawl only one branch per book?*Created by: seanmadsen*
Sometimes I am searching for docs in other projects and the google results take me to a version-specific docs page, which sometimes is outdated. Other times google will display separate results for separate vers...*Created by: seanmadsen*
Sometimes I am searching for docs in other projects and the google results take me to a version-specific docs page, which sometimes is outdated. Other times google will display separate results for separate versions, both with the same content, which is somewhat confusing. Also my limited understanding of SEO tells me that this is bad SEO, too.
I wonder if it would be easy/possible/desirable for us to make civicrm-docs generate a `robots.txt` file or something else that will tell search engines to only index *one* version of each book. Maybe "latest", maybe "stable".
This issue will only become relevant once the auto-generated docs home page is in place.
Low priority. Just a thought. Docs Publisher 2019homotechsualhomotechsualhttps://lab.civicrm.org/documentation/docs-publisher/-/issues/16Book validation during publishing2019-05-21T10:16:40ZSean ColsenBook validation during publishing*Created by: seanmadsen*
Perform some simple validation steps when publishing a book.
For example `ack '\!\[.*\]\((.*?)( ".*)?\)' -h --nobreak --output='$1'` will give all images. We can check whether they exist.
migrated from [...*Created by: seanmadsen*
Perform some simple validation steps when publishing a book.
For example `ack '\!\[.*\]\((.*?)( ".*)?\)' -h --nobreak --output='$1'` will give all images. We can check whether they exist.
migrated from [to-do list](https://github.com/civicrm/civicrm-docs/tree/638e243c6f4eb06086199e3ea8b529541368f688#to-do).Docs Publisher 2019homotechsualhomotechsualhttps://lab.civicrm.org/documentation/docs-publisher/-/issues/13Find a more usable web-based UI for simple editing2019-05-21T10:16:19ZSean ColsenFind a more usable web-based UI for simple editing*Created by: seanmadsen*
find a nice user-friendly UI for people to edit the documentation (the github UI is OK but we can do better)
migrated from [to-do list](https://github.com/civicrm/civicrm-docs/tree/638e243c6f4eb06086199e3ea8b...*Created by: seanmadsen*
find a nice user-friendly UI for people to edit the documentation (the github UI is OK but we can do better)
migrated from [to-do list](https://github.com/civicrm/civicrm-docs/tree/638e243c6f4eb06086199e3ea8b529541368f688#to-do).Docs Publisher 2019homotechsualhomotechsualhttps://lab.civicrm.org/documentation/docs-publisher/-/issues/12seperate repo for app/config/books2019-07-17T08:28:03ZSean Colsenseperate repo for app/config/books*Created by: seanmadsen*
create a seperate repo for app/config/books where we can define books independently of this repo
migrated from [to do list](https://github.com/civicrm/civicrm-docs/tree/638e243c6f4eb06086199e3ea8b529541368f68...*Created by: seanmadsen*
create a seperate repo for app/config/books where we can define books independently of this repo
migrated from [to do list](https://github.com/civicrm/civicrm-docs/tree/638e243c6f4eb06086199e3ea8b529541368f688#to-do)Docs Publisher 2019homotechsualhomotechsualhttps://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/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-17