Docs Publisher issueshttps://lab.civicrm.org/documentation/docs-publisher/-/issues2018-11-08T04:23:30Zhttps://lab.civicrm.org/documentation/docs-publisher/-/issues/21Change docs system to work with Apache instead of nginx2018-11-08T04:23:30ZSean ColsenChange docs system to work with Apache instead of nginx*Created by: seanmadsen*
@michaelmcandrew and I talked on Mattermost yesterday about the steps needed to implement [internal redirects](https://github.com/civicrm/civicrm-docs/issues/20) for each book, which is a high-priority issue, sl...*Created by: seanmadsen*
@michaelmcandrew and I talked on Mattermost yesterday about the steps needed to implement [internal redirects](https://github.com/civicrm/civicrm-docs/issues/20) for each book, which is a high-priority issue, slowing the progress of content migration within the Developer Guide. Michael recommended that switching the server from nginx to Apache would make this internal redirects project easier. This issues requires changes within the docs app so that it runs reliably on Apache, including reading and [manual publishing via URL](https://github.com/civicrm/civicrm-docs#manual-publishing). https://lab.civicrm.org/documentation/docs-publisher/-/issues/25Clarify role (user / admininstrator / developer) terminology2017-04-30T22:16:43ZSean ColsenClarify role (user / admininstrator / developer) terminology*Created by: michaelmcandrew*
The words user and developer are pretty clear.
Administrator is ambigious since it can refer to
* an advanced user that sets things up for other users using the UI
* a system administrator that doe...*Created by: michaelmcandrew*
The words user and developer are pretty clear.
Administrator is ambigious since it can refer to
* an advanced user that sets things up for other users using the UI
* a system administrator that does stuff like install, host, and is familiar with CLI, SSH, FTP, DNS, etc.
I'm not sure that coming up with a rule like "administrator MUST only be used to signify system administrator" is a good idea since language is nuanced. On the other hand, if we could could up with an acceptable phase for an "advanced user that does set up" that might change my mind.
Alternatively, just some sensible guidance on how we refer to different roles would be good to have in the documentation guidelines.https://lab.civicrm.org/documentation/docs-publisher/-/issues/17Create "Administrator Guide" book, separate from User Guide and Developer Guide2018-11-08T04:23:30ZSean ColsenCreate "Administrator Guide" book, separate from User Guide and Developer Guide*Created by: seanmadsen*
We currently have a User Guide and a Developer Guide. The addition of an Administrator Guide would round out the documentation and cover topics such as installing/updating core, finding/installing extensions, ...*Created by: seanmadsen*
We currently have a User Guide and a Developer Guide. The addition of an Administrator Guide would round out the documentation and cover topics such as installing/updating core, finding/installing extensions, and basic troubleshooting. Some of this content is currently in the User Guide (e.g. [here](https://docs.civicrm.org/user/en/stable/initial-set-up/installation-and-basic-set-up/)) and some of it is in the wiki (e.g. [here](https://wiki.civicrm.org/confluence/display/CRMDOC/Installation+and+Upgrades)).
migrated from [to-do list](https://github.com/civicrm/civicrm-docs/tree/638e243c6f4eb06086199e3ea8b529541368f688#to-do).https://lab.civicrm.org/documentation/docs-publisher/-/issues/30Create book categorization functionality2017-04-30T22:16:43ZSean ColsenCreate book categorization functionality*Created by: seanmadsen*
I would like for civicrm-docs to be capable of hosting extension-specific books eventually. I can imagine a day when there are a handful of books core-related books (e.g. User, Admin, Dev), plus over a dozen ext...*Created by: seanmadsen*
I would like for civicrm-docs to be capable of hosting extension-specific books eventually. I can imagine a day when there are a handful of books core-related books (e.g. User, Admin, Dev), plus over a dozen extension-specific books. When this day comes, having a docs home page that separates core-related books from extension-specific books will make the home page easier to navigate.
I propose the following is added to a book's `.yml` config file:
```yaml
category: core
```
or
```yaml
category: extension
```
If this setting is missing, then the app would assume "extension".
After these categories are in place, the home page can be modified to display books separately by category.
Why do this now, when there are zero extension-specific books? — I think that if we can get *one* extension-specific book in there and make the home page look really slick and well-organized, it will help motivate other extensions maintainers to set up their own docs in books. https://lab.civicrm.org/documentation/docs-publisher/-/issues/31Create book sorting functionality2017-04-30T22:16:43ZSean ColsenCreate book sorting functionality*Created by: seanmadsen*
Currently the home page lists books alphabetically. I'd like to eventually show books in the following order:
* User Guide
* Administrator Guide
* Developer Guide
I'm proposing adding a new configuratio...*Created by: seanmadsen*
Currently the home page lists books alphabetically. I'd like to eventually show books in the following order:
* User Guide
* Administrator Guide
* Developer Guide
I'm proposing adding a new configuration value to each book's `.yml` file as follows:
```yaml
weight: 2
```
Then books could be assigned specific weights and ordered as such. https://lab.civicrm.org/documentation/docs-publisher/-/issues/69Create theme customization for displaying horizontal rule elements within men...2021-09-27T11:21:30ZSean ColsenCreate theme customization for displaying horizontal rule elements within menu itemsWe'd like to be able to separate top-level menu items with `<hr>` elements.
If you put this into `mkdocs.yml` it mostly works...
```yaml
- Extensions Development:
- Basics: extensions/index.md
- <hr/>Framework Reference:
```
But th...We'd like to be able to separate top-level menu items with `<hr>` elements.
If you put this into `mkdocs.yml` it mostly works...
```yaml
- Extensions Development:
- Basics: extensions/index.md
- <hr/>Framework Reference:
```
But the CSS prevents the `<hr>` element from being visible. We need to improve this CSS so that `<hr>` elements within the menu display nicely. Do this as part of our custom theme extension.
This discussion started here: https://chat.civicrm.org/civicrm/pl/nmrzugcc9p81jr4ktp1iydjd5whttps://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/15Custom theme2018-11-08T04:23:30ZSean ColsenCustom theme*Created by: seanmadsen*
A CiviCRM theme for documentation with the following goals:
* display the version branch version (e.g. in user guide, show "4.6" or "latest")
* link to docs.civicrm.org documentation home page (to allow us...*Created by: seanmadsen*
A CiviCRM theme for documentation with the following goals:
* display the version branch version (e.g. in user guide, show "4.6" or "latest")
* link to docs.civicrm.org documentation home page (to allow user to switch between books/versions/etc)
* link to civicrm.org home page
* colors/branding matching CiviCRM branding, to some degree (not aiming for 100% match here, but at least a little bit)
* more control over future theme-level features as needed
migrated from [to-do list](https://github.com/civicrm/civicrm-docs/tree/638e243c6f4eb06086199e3ea8b529541368f688#to-do).https://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/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/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/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/55don't use "admin" as a path component for app functionality2017-10-09T22:42:55ZSean Colsendon't use "admin" as a path component for app functionality*Created by: seanmadsen*
Currently we have these two routes which Symfony handles: `/admin/publish` and `/admin/listen`. I think it's likely that we'll eventually want to have a book with the slug `admin` which complicates this routing....*Created by: seanmadsen*
Currently we have these two routes which Symfony handles: `/admin/publish` and `/admin/listen`. I think it's likely that we'll eventually want to have a book with the slug `admin` which complicates this routing.
I'd like to change those routes to `/system/publish` and `/system/listen` respectively. I think it's unlikely enough that we'll ever want a book with the slug `system`. https://lab.civicrm.org/documentation/docs-publisher/-/issues/80Editing non-master branches with the pencil icon doesn't work2017-10-19T15:10:25ZSean ColsenEditing non-master branches with the pencil icon doesn't workSteps to reproduce:
1. Go to the home page of the User Guide 4.6 edition
https://docs.civicrm.org/user/en/4.6/
1. Hover over the pencil icon at the top right of the page
1. Expect the URL to be
https://github.com/civicrm/civic...Steps to reproduce:
1. Go to the home page of the User Guide 4.6 edition
https://docs.civicrm.org/user/en/4.6/
1. Hover over the pencil icon at the top right of the page
1. Expect the URL to be
https://github.com/civicrm/civicrm-user-guide/edit/4.6/docs/index.md
1. Observe the URL to be
https://github.com/civicrm/civicrm-user-guide/edit/master/docs/index.mdhttps://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/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/34Force a standard set of markdown extensions to be enabled for all books2017-04-30T22:16:43ZSean ColsenForce a standard set of markdown extensions to be enabled for all books*Created by: seanmadsen*
There are some markdown extensions that we basically just want to be enabled all the time, even if each book's `mkdocs.yml` file doesn't enable them. I think we should force them to be enabled at [this point in ...*Created by: seanmadsen*
There are some markdown extensions that we basically just want to be enabled all the time, even if each book's `mkdocs.yml` file doesn't enable them. I think we should force them to be enabled at [this point in the code](https://github.com/civicrm/civicrm-docs/blob/master/src/AppBundle/Utils/Publisher.php#L103).
It should set the following:
```yaml
markdown_extensions:
- attr_list
- admonition
- codehilite
- toc(permalink=true)
- pymdownx.superfences
- pymdownx.inlinehilite
- pymdownx.tilde
- pymdownx.betterem
```
More details within [Material's docs](http://squidfunk.github.io/mkdocs-material/extensions/pymdown/)https://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/26home page - add some more info about docs, generally2017-04-30T22:16:43ZSean Colsenhome page - add some more info about docs, generally*Created by: seanmadsen*
If we want to redirect civicrm.org/documentation to docs.civicrm.org eventually, we'll need some more info on the docs home page.
Michael [said](https://github.com/civicrm/civicrm-docs/issues/18#issuecomment...*Created by: seanmadsen*
If we want to redirect civicrm.org/documentation to docs.civicrm.org eventually, we'll need some more info on the docs home page.
Michael [said](https://github.com/civicrm/civicrm-docs/issues/18#issuecomment-273431305) It does need a bit of fleshing out. Copying content from http://civicrm.org/documentation to https://github.com/civicrm/civicrm-docs/blob/master/src/AppBundle/Resources/views/Read/home.html.twig https://lab.civicrm.org/documentation/docs-publisher/-/issues/28Home page - books missing2017-04-30T22:16:43ZSean ColsenHome page - books missing*Created by: seanmadsen*
In my local installation of civicrm-docs I see a home page which lists the User Guide but does not list the Dev Guide. When I publish all books via command line the Dev Guide is include in this publishing proces...*Created by: seanmadsen*
In my local installation of civicrm-docs I see a home page which lists the User Guide but does not list the Dev Guide. When I publish all books via command line the Dev Guide is include in this publishing process, so the app is well aware of the existence of the Dev Guide. Tim also [observed](https://chat.civicrm.org/civicrm/pl/7fh9y7w5o7d458yukjsuf33mby) the same behavior.