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/64Implement Search Across More Than One Book2021-09-27T11:22:24ZskesslerImplement Search Across More Than One BookSince we are breaking extensions off into their own books there is lots of value of allowing users to search through multiple books.
For example, if you are an end user interested in discounts you may not know to go to the book on Civi...Since we are breaking extensions off into their own books there is lots of value of allowing users to search through multiple books.
For example, if you are an end user interested in discounts you may not know to go to the book on CiviDiscount. You are going to most likely go to the CiviCRM Documentation and click *User Guide* not knowing where else to go.
I propose we add a search that allows searches of all of the *latest* books.
![Search_CiviCRM_Documentation](/uploads/de8a9bd56370757c442beabc711b83f4/Search_CiviCRM_Documentation.png)
I do not think that we should allow searches over all the branches. It will be too confusing. I do think we need to let people select the language like in the graphic above.
Thanks,
Stevehomotechsualhomotechsualhttps://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/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/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/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/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/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/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 2019homotechsualhomotechsual