Docs Publisher issues
https://lab.civicrm.org/documentation/docs-publisher/-/issues
2017-04-30T22:16:43Z
https://lab.civicrm.org/documentation/docs-publisher/-/issues/63
Move this repo to GitLab
2017-04-30T22:16:43Z
Sean Colsen
Move this repo to GitLab
*Created by: seanmadsen*
We are starting to test the waters with GitLab at https://lab.civicrm.org. I'd like to migrate this repository (and our workflow) there. Is that okay with others? I'd especially like to get the go-ahead from @mi...
*Created by: seanmadsen*
We are starting to test the waters with GitLab at https://lab.civicrm.org. I'd like to migrate this repository (and our workflow) there. Is that okay with others? I'd especially like to get the go-ahead from @michaelmcandrew here. What do you think?
https://lab.civicrm.org/documentation/docs-publisher/-/issues/62
Re-title wiki.civicrm.org so Docs site is preferred
2017-04-30T22:16:43Z
xurizaemon
Re-title wiki.civicrm.org so Docs site is preferred
Currently searches for "civicrm docs" have the wiki at the top. By now I think we should be preferring to land people on docs.civicrm.org and linking to "legacy" docs in the wiki when necessary.
Not sure what is required to re-title w...
Currently searches for "civicrm docs" have the wiki at the top. By now I think we should be preferring to land people on docs.civicrm.org and linking to "legacy" docs in the wiki when necessary.
Not sure what is required to re-title wiki.civicrm.org "CiviCRM Wiki" or "Legacy Documentation" to denote this, so opening an issue to propose it.
![screen shot 2017-04-22 at 11 51 08 pm](https://cloud.githubusercontent.com/assets/105608/25304220/f191eb42-27b6-11e7-8990-86498772896b.png)
https://lab.civicrm.org/documentation/docs-publisher/-/issues/56
Say "guides" instead of "books"
2017-04-30T22:16:43Z
Sean Colsen
Say "guides" instead of "books"
*Created by: seanmadsen*
Remove language about "books", and change it to "guides" instead.
I think the home page is the only place where this change is needed within this repository.
Convo originally started by @michaelmcandrew ...
*Created by: seanmadsen*
Remove language about "books", and change it to "guides" instead.
I think the home page is the only place where this change is needed within this repository.
Convo originally started by @michaelmcandrew [here](https://chat.civicrm.org/civicrm/pl/ksz16ognw3dxim6s8mmixh69pe)
https://lab.civicrm.org/documentation/docs-publisher/-/issues/54
Implement "watchers" email addresses in book config files
2017-04-30T22:16:43Z
Sean Colsen
Implement "watchers" email addresses in book config files
*Created by: seanmadsen*
This feature was there before my refactor, but I didn't carry it through since none of the books were actually using it.
The idea here is that in a book's yaml config file, one could specify a list of email ...
*Created by: seanmadsen*
This feature was there before my refactor, but I didn't carry it through since none of the books were actually using it.
The idea here is that in a book's yaml config file, one could specify a list of email addresses which should always be notified during the publishing process. This list should be specified at the "language" level for a book.
https://lab.civicrm.org/documentation/docs-publisher/-/issues/44
remove docs:serve command
2017-04-30T22:16:43Z
Sean Colsen
remove docs:serve command
*Created by: seanmadsen*
Hey @totten I [see](https://github.com/civicrm/civicrm-docs/commit/5ea1844066be02463bc71042dd8521dcb2a8936c) that last year you added the `docs:serve` command. Do you use this command? I'm wondering if we can re...
*Created by: seanmadsen*
Hey @totten I [see](https://github.com/civicrm/civicrm-docs/commit/5ea1844066be02463bc71042dd8521dcb2a8936c) that last year you added the `docs:serve` command. Do you use this command? I'm wondering if we can remove it. I've been doing a [whole bunch of refactoring](https://github.com/seanmadsen/civicrm-docs/commits/refactor-model) (so far just in my own fork) and when I came across `docs:serve` I said "hmm, this is a cool idea, but I'm not sure it's worth maintaining, given the ease of running `mkdocs serve`", so I [removed it](https://github.com/seanmadsen/civicrm-docs/commit/1e9da6a0e40e38ef3da4277ca85e183bec46eb31). It wouldn't be too hard for me to put it back, and update the code to conform to some of the changes in my refactor, but I wonder how you'd feel about dropping this functionality from civicrm-docs to keep the app's purpose more focused on publishing.
https://lab.civicrm.org/documentation/docs-publisher/-/issues/42
Set up theme customizations
2017-04-30T22:16:43Z
Sean Colsen
Set up theme customizations
*Created by: seanmadsen*
*Created by: seanmadsen*
https://lab.civicrm.org/documentation/docs-publisher/-/issues/40
better CSS for definition lists
2017-04-30T22:16:43Z
Sean Colsen
better CSS for definition lists
*Created by: seanmadsen*
Some definition lists on the [extension life cycle](https://docs.civicrm.org/dev/en/master/extend-stages/#definitions) page. the `dt` items looked a little nicer with the readthedocs theme. Would be quick and us...
*Created by: seanmadsen*
Some definition lists on the [extension life cycle](https://docs.civicrm.org/dev/en/master/extend-stages/#definitions) page. the `dt` items looked a little nicer with the readthedocs theme. Would be quick and useful to add a little style that makes the terms pop out a bit more
https://lab.civicrm.org/documentation/docs-publisher/-/issues/38
"watch page" feature
2017-04-30T22:16:43Z
Sean Colsen
"watch page" feature
*Created by: seanmadsen*
It'd be great if a person choose to get email notifications any time someone else changed a page, kind of like in a wiki.
*Created by: seanmadsen*
It'd be great if a person choose to get email notifications any time someone else changed a page, kind of like in a wiki.
https://lab.civicrm.org/documentation/docs-publisher/-/issues/36
How do we include theme customizations in this repo?
2017-04-30T22:16:43Z
Sean Colsen
How do we include theme customizations in this repo?
*Created by: seanmadsen*
So, we have a separate repository, [civicrm-docs-material](https://github.com/civicrm/civicrm-docs-material) for the theme customizations which was part of my [plan](https://github.com/civicrm/civicrm-docs/issue...
*Created by: seanmadsen*
So, we have a separate repository, [civicrm-docs-material](https://github.com/civicrm/civicrm-docs-material) for the theme customizations which was part of my [plan](https://github.com/civicrm/civicrm-docs/issues/15#issuecomment-276156953), but now I'm doubting this choice a bit, after talking with @michaelmcandrew today. I'd like some advice on the best way to proceed here, especially from @totten
The theme customizations need to be accessible (and current)
* (A): on www-prod when publishing books
* (B): locally for theme developers to use with `mkdocs serve`
* (C): locally for civicrm-docs developers after doing `civibuild docs`
So the question is, how do we store the theme customizations to best meet all these needs. Here are ideas that emerged from my convo with Michael
1. `civicrm-docs-material` as a git submodule within `civicrm-docs`
1. theme customizations stored within `civicrm-docs` directly (and we get rid of the separate repo)
1. something else?
I don't have an opinion. Do others? (Sorry if it was a bit premature to create that new repo and add 6 issues within it! :grimacing: )
https://lab.civicrm.org/documentation/docs-publisher/-/issues/34
Force a standard set of markdown extensions to be enabled for all books
2017-04-30T22:16:43Z
Sean Colsen
Force 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/33
How will users switch between different versions of a book?
2017-04-30T22:16:43Z
Sean Colsen
How will users switch between different versions of a book?
*Created by: seanmadsen*
@nganivet [raised the issue](https://github.com/civicrm/civicrm-docs/issues/15#issuecomment-275983259) of documentation users needing a clear and usable way to switch between different versions of a book. For ex...
*Created by: seanmadsen*
@nganivet [raised the issue](https://github.com/civicrm/civicrm-docs/issues/15#issuecomment-275983259) of documentation users needing a clear and usable way to switch between different versions of a book. For example if a user lands on the User Guide for CiviCRM 4.6, how does this user switch to the User Guide for the most current version? What indication does the user even have that they could potentially be reading an outdated version of the docs?
@nganivet included this screedshot in the original discussion as an example:
![screenshot](https://cloud.githubusercontent.com/assets/3435067/22413152/9cb83444-e672-11e6-97e2-77081c3aab79.png)
https://lab.civicrm.org/documentation/docs-publisher/-/issues/32
Migrating content from stack exchange to docs
2017-04-30T22:16:43Z
Sean Colsen
Migrating content from stack exchange to docs
*Created by: michaelmcandrew*
It strikes me that Stack Exchange is potentially a great source of inspiration / content for our documentation. http://civicrm.stackexchange.com/questions?sort=votes has a list of topics that we should ensu...
*Created by: michaelmcandrew*
It strikes me that Stack Exchange is potentially a great source of inspiration / content for our documentation. http://civicrm.stackexchange.com/questions?sort=votes has a list of topics that we should ensure are represented in the docs.
I imagine post popular *answers* as well would be useful but I can't find the an appropriate URL for that.
We can use the content from SE as (a starting point) for the actual text, and link to the docs from a comment on the question / answer, if relevant.
Not sure what labels to attach to the issue, but thought it was worth capturing / discussing...
https://lab.civicrm.org/documentation/docs-publisher/-/issues/31
Create book sorting functionality
2017-04-30T22:16:43Z
Sean Colsen
Create 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/30
Create book categorization functionality
2017-04-30T22:16:43Z
Sean Colsen
Create 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/28
Home page - books missing
2017-04-30T22:16:43Z
Sean Colsen
Home 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.
https://lab.civicrm.org/documentation/docs-publisher/-/issues/27
Home page - improve visual style
2017-04-30T22:16:43Z
Sean Colsen
Home page - improve visual style
*Created by: seanmadsen*
Would be great to get the branding on the docs home page to match that on civicrm.org. For example, putting the logo up there, and using the same font, colors, etc.
*Created by: seanmadsen*
Would be great to get the branding on the docs home page to match that on civicrm.org. For example, putting the logo up there, and using the same font, colors, etc.
https://lab.civicrm.org/documentation/docs-publisher/-/issues/26
home page - add some more info about docs, generally
2017-04-30T22:16:43Z
Sean Colsen
home 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/25
Clarify role (user / admininstrator / developer) terminology
2017-04-30T22:16:43Z
Sean Colsen
Clarify 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/23
"Edit on GitHub" should take user to specific page
2017-04-30T22:16:43Z
Sean Colsen
"Edit on GitHub" should take user to specific page
*Created by: seanmadsen*
When reading a guide book, the reader/user can click a link at the top right to "Edit on GitHub". This link takes the user to the root of the GitHub repository. From that point, the user does not have an intuiti...
*Created by: seanmadsen*
When reading a guide book, the reader/user can click a link at the top right to "Edit on GitHub". This link takes the user to the root of the GitHub repository. From that point, the user does not have an intuitive way of finding the page to edit. It would be nice if the "edit" link took the user to edit exactly the page being viewed.
https://lab.civicrm.org/documentation/docs-publisher/-/issues/22
Provide language and version switching capability within books
2017-04-30T22:16:43Z
Sean Colsen
Provide language and version switching capability within books
*Created by: seanmadsen*
The User Guide has multiple versions and multiple languages, all of which are listed on https://civicrm.org/documentation but many URLs for this guide point only to the latest English version at https://docs.civ...
*Created by: seanmadsen*
The User Guide has multiple versions and multiple languages, all of which are listed on https://civicrm.org/documentation but many URLs for this guide point only to the latest English version at https://docs.civicrm.org/user/en/latest/. Once a reader arrives there, it is not apparent that they have the option to read the guide in other languages or for other versions.
https://lab.civicrm.org/documentation/docs-publisher/-/issues/64
Implement Search Across More Than One Book
2021-09-27T11:22:24Z
skessler
Implement Search Across More Than One Book
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 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,
Steve
homotechsual
homotechsual
https://lab.civicrm.org/documentation/docs-publisher/-/issues/65
Add 1px Boarder for Images
2021-09-27T11:21:55Z
skessler
Add 1px Boarder for Images
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.
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 2019
homotechsual
homotechsual
https://lab.civicrm.org/documentation/docs-publisher/-/issues/66
Custom style for external hyperlinks to indicate to the reader that they are ...
2021-09-27T11:21:42Z
Sean Colsen
Custom style for external hyperlinks to indicate to the reader that they are external
When 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 #61
When 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 #61
homotechsual
homotechsual
https://lab.civicrm.org/documentation/docs-publisher/-/issues/67
Delete NotifyControllerTest.php
2019-05-21T09:59:45Z
Sean Colsen
Delete 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/68
Build books to a temporary directory before publishing
2017-10-09T22:39:38Z
Sean Colsen
Build books to a temporary directory before publishing
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 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 #39
https://lab.civicrm.org/documentation/docs-publisher/-/issues/69
Create theme customization for displaying horizontal rule elements within men...
2021-09-27T11:21:30Z
Sean Colsen
Create theme customization for displaying horizontal rule elements within menu items
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 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/nmrzugcc9p81jr4ktp1iydjd5w
https://lab.civicrm.org/documentation/docs-publisher/-/issues/70
Visual mess when search results appear on top of admonitions
2021-09-27T11:21:09Z
Sean Colsen
Visual mess when search results appear on top of admonitions
We probably have some sort small error in our theme customization which is causing this.
For example:
![screenshot63](/uploads/5bc214bf688f26926f52f9d048c304c9/screenshot63.png)
Compare to vanilla Material which does not exhibit this...
We probably have some sort small error in our theme customization which is causing this.
For example:
![screenshot63](/uploads/5bc214bf688f26926f52f9d048c304c9/screenshot63.png)
Compare to vanilla Material which does not exhibit this behavior:
![screenshot64](/uploads/aa052f00fd5c9ba130642871645478b6/screenshot64.png)
CC: @michael
https://lab.civicrm.org/documentation/docs-publisher/-/issues/71
Update information in the footer/bottom area
2017-07-31T16:05:29Z
josh
josh@civicrm.org
Update information in the footer/bottom area
Would be good to add in a footer consistent with civicrm.org:
© 2005 - 2017, CIVICRM LLC. All rights reserved.
CiviCRM and the CiviCRM logo are trademarks of CIVICRM LLC. Except where otherwise noted, content on this site is licensed un...
Would be good to add in a footer consistent with civicrm.org:
© 2005 - 2017, CIVICRM LLC. All rights reserved.
CiviCRM and the CiviCRM logo are trademarks of CIVICRM LLC. Except where otherwise noted, content on this site is licensed under a Creative Commons Attribution-Share Alike 3.0 United States Licence.
Also, might be nice to expand on the content to "support" (http://civicrm.org/support-us) CiviCRM. Some might want to help with documentation whereas others might want to make a small gift.
https://lab.civicrm.org/documentation/docs-publisher/-/issues/72
Repo URLs specificed in yaml files shold be acceptable with trailing slashes
2020-04-26T20:35:47Z
Sean Colsen
Repo URLs specificed in yaml files shold be acceptable with trailing slashes
[Here](https://chat.civicrm.org/civicrm/pl/4unpux1jgpbpxxjby5ioh89x6o) was a conversation where a trailing slash led to errors when trying to publish a book from a GitHub webhook request. We should allow the trailing slash in the URL so ...
[Here](https://chat.civicrm.org/civicrm/pl/4unpux1jgpbpxxjby5ioh89x6o) was a conversation where a trailing slash led to errors when trying to publish a book from a GitHub webhook request. We should allow the trailing slash in the URL so that this error doesn't happen again.
https://lab.civicrm.org/documentation/docs-publisher/-/issues/73
Change CSS for monospace hyperlinks so that it's apparent that they are links
2021-09-27T11:20:53Z
Sean Colsen
Change CSS for monospace hyperlinks so that it's apparent that they are links
In [this page](https://docs.civicrm.org/dev/en/latest/extensions/info-xml/#extension) there are a lot of hyperlinks which contain only monospace text. The current style makes it hard for the user to understand that these are actually lin...
In [this page](https://docs.civicrm.org/dev/en/latest/extensions/info-xml/#extension) there are a lot of hyperlinks which contain only monospace text. The current style makes it hard for the user to understand that these are actually links. Change CSS to make these look different (e.g. underline).
Check with upstream Material Theme to make sure they haven't already made this fix, and consider reporting to them.
https://lab.civicrm.org/documentation/docs-publisher/-/issues/61
Open external links in a new tab/window.
2019-05-21T10:20:19Z
Sean Colsen
Open 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 2019
homotechsual
homotechsual
https://lab.civicrm.org/documentation/docs-publisher/-/issues/60
Automatic publishing for books hosted in GitLab
2019-05-21T10:18:44Z
Sean Colsen
Automatic 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.
michael
michael
https://lab.civicrm.org/documentation/docs-publisher/-/issues/59
When acting on GitHub webhooks, only publish if docs content was modified
2019-05-21T10:19:35Z
Sean Colsen
When 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 2019
homotechsual
homotechsual
https://lab.civicrm.org/documentation/docs-publisher/-/issues/58
Allow aliases for book slugs
2019-05-21T10:17:41Z
Sean Colsen
Allow 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 books
Docs Publisher 2019
homotechsual
homotechsual
https://lab.civicrm.org/documentation/docs-publisher/-/issues/55
don't use "admin" as a path component for app functionality
2017-10-09T22:42:55Z
Sean Colsen
don'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/53
Get details for email notifications from git repo instead of POST request
2019-05-21T10:18:15Z
Sean Colsen
Get 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 2019
homotechsual
homotechsual
https://lab.civicrm.org/documentation/docs-publisher/-/issues/52
Better handle concurrent requests to publish the same edition
2019-05-21T10:00:19Z
Sean Colsen
Better handle concurrent requests to publish the same edition
*Created by: seanmadsen*
Deal more gracefully with the situation where a request to publish an edition is submitted while the system is currently in the process of publishing that edition.
Probably we want to create a lock file when ...
*Created by: seanmadsen*
Deal more gracefully with the situation where a request to publish an edition is submitted while the system is currently in the process of publishing that edition.
Probably we want to create a lock file when beginning the publishing process and remove this file upon completion.
The second request could be queued or discarded. I think it's best to discard it.
https://lab.civicrm.org/documentation/docs-publisher/-/issues/51
User Guide - label 4.7 as "Latest" and 4.6 as "LTS"
2017-10-19T15:00:17Z
Sean Colsen
User Guide - label 4.7 as "Latest" and 4.6 as "LTS"
*Created by: seanmadsen*
This is in response to a request from @nganivet [here](https://github.com/civicrm/civicrm-docs/pull/49#issuecomment-286637921). Specific changes to implement:
* [x] Update [civicrm.org/documentation](https://ci...
*Created by: seanmadsen*
This is in response to a request from @nganivet [here](https://github.com/civicrm/civicrm-docs/pull/49#issuecomment-286637921). Specific changes to implement:
* [x] Update [civicrm.org/documentation](https://civicrm.org/documentation) to change the URL for User Guide 4.7 from `/user/en/stable` to `/user/en/latest` **(Done by Sean on 2017-03-15)**
* [x] Redirect `user/en/stable` to `/user/en/latest` **(Blocked by #50)** *(Note: this change is just to avoid giving 404s to any "stable" URLs which still exist in the wild, since people have been using this URL for the 4.7 version of the User Guide for quite some time now. The term "stable" would not be displayed to any readers anywhere, but would just function as a redirect)*
* [x] Redirect `/user/en/lts` to `/user/en/4.6` **(Blocked by #50)**
* [x] When describing the available editions of the User Guide to readers, do it as follows: **(Blocked by #50 and #48 and #46 )** *(Note: these descriptors will eventually be used in the auto-generated book home pages, as well as at the top of every page within the book when the book is built with the Material theme customizations)*
* "English – 4.7 (Latest)"
* "English – 4.6 (LTS)"
* "françias (French) – 4.7 (Latest)"
https://lab.civicrm.org/documentation/docs-publisher/-/issues/50
Allow book versions to be defined in a more flexible way
2017-10-19T14:59:04Z
Sean Colsen
Allow book versions to be defined in a more flexible way
*Created by: seanmadsen*
## Our current config schema
The way this app currently works, you define a book like this:
```yaml
name: User Guide
langs:
en:
repo: 'https://github.com/civicrm/civicrm-user-guide'
latest:...
*Created by: seanmadsen*
## Our current config schema
The way this app currently works, you define a book like this:
```yaml
name: User Guide
langs:
en:
repo: 'https://github.com/civicrm/civicrm-user-guide'
latest: master
stable: 4.7
history:
- 4.6
```
## End-user example from Symfony
There are a number of limitations with our current approach. For the sake of time, I won't summarize them all. But I will offer an example of the end-user experience of choosing a version within [Symfony's documentation](http://symfony.com/doc/current/setup.html):
![screenshot13](https://cloud.githubusercontent.com/assets/42411/23837987/42fc6204-0756-11e7-8ddd-cbf115ca701b.png)
I like the way this works. When you click on "3.2 / Current" you're taken to `/doc/current/`. If you manually enter the URL `/doc/3.2/` you get redirected to `/doc/current`. Very slick. Very usable.
## Proposed new config schema
I want to change it to this:
```yaml
name: User Guide
default_language: en
languages:
en:
repo: 'https://github.com/civicrm/civicrm-user-guide'
default_version: 4.7
watchers:
- sean@seanmadsen.com
versions:
4.7: # This is stored as $slug
name: 4.7 / Current # If omitted, use $slug
path: current # If omitted, use a URL-safe version of $slug
branch: master # If omitted, use $slug
visible: true # If omitted, use "true"
maintained: true # If omitted, use "true"
redirects: # These are not displayed anywhere
- latest
4.6:
branch: 4.6
name: 4.6 / LTS
redirects:
- lts
4.5:
branch: 4.5
visible: false
maintained: false
```
Here's what each of those settings would actually *do*:
- `slug` - basically just used to organize the settings within the yaml file
- `name` - this is what the user sees when choosing between different versions, and at the top of every page when viewing the book
- `path` - this is used for the version component of the URL
- `branch` - tells us what branch to use in the git repo
- `visible` - when true, display this version in lists of different versions presented to the user. When false, don't display this version in navigation, but still allow its content to be published and viewed
- `maintained` - when this is false, display something like "(unmaintained)" to the user in various contexts such as choosing between different versions and (possible) when viewing the book
- `redirects` - when a user requests a URL with one of the listed redirects in place of `path`, the app will redirect the user to the correct URL that uses `path`. Both `branch` and `slug` will automatically function as redirects when their values differ from `path`.
I'm curious to hear feedback from others about this proposal. If I don't hear any concerns within 5 days, I'll begin the work to implement this proposal.
https://lab.civicrm.org/documentation/docs-publisher/-/issues/35
Restrict web crawler bots to crawl only one branch per book?
2019-05-21T10:12:45Z
Sean Colsen
Restrict 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 2019
homotechsual
homotechsual
https://lab.civicrm.org/documentation/docs-publisher/-/issues/24
The "Publishing" email notificiations should include commit messages
2017-10-12T14:36:37Z
Sean Colsen
The "Publishing" email notificiations should include commit messages
*Created by: seanmadsen*
When civicrm-docs publishes a book, it send out an email notification. It would be helpful if, within these email messages, it could include the commit messages (and authors) of the changes published. This way p...
*Created by: seanmadsen*
When civicrm-docs publishes a book, it send out an email notification. It would be helpful if, within these email messages, it could include the commit messages (and authors) of the changes published. This way people who didn't make changes but still got the email will see what happened.
This is low priority. Just a thought.
michael
michael
https://lab.civicrm.org/documentation/docs-publisher/-/issues/74
Pressing Enter when searching reloads current page
2021-09-27T11:20:39Z
Sean Colsen
Pressing Enter when searching reloads current page
This is most likely an upstream issue with [MkDocs Material](https://github.com/squidfunk/mkdocs-material) and we should report it there (or see if it's already been fixed).
Steps to reproduce:
1. Go to a documentation page
1. Enter a...
This is most likely an upstream issue with [MkDocs Material](https://github.com/squidfunk/mkdocs-material) and we should report it there (or see if it's already been fixed).
Steps to reproduce:
1. Go to a documentation page
1. Enter a search term in the search bar
1. Note that it usually takes a while to see results
1. Press `Enter` (maybe because you're not sure if the search is actually running)
1. Expect nothing to happen after pressing `Enter`
1. Observe that the search is canceled and the current page is reloaded.
ref: https://chat.civicrm.org/civicrm/pl/co9zoo34r7rp3f5oyoofk4rqhe
https://lab.civicrm.org/documentation/docs-publisher/-/issues/75
Searching guides is slow
2021-09-27T11:20:30Z
Sean Colsen
Searching guides is slow
Searching within a guide is quite slow. The results appear, but after a significant delay. Larger guides have larger delays.
This is an upstream issue with [MkDocs Material](https://github.com/squidfunk/mkdocs-material). There might be ...
Searching within a guide is quite slow. The results appear, but after a significant delay. Larger guides have larger delays.
This is an upstream issue with [MkDocs Material](https://github.com/squidfunk/mkdocs-material). There might be nothing we can do here, but it could be worth researching it a bit.
https://lab.civicrm.org/documentation/docs-publisher/-/issues/76
Search gives no indication that it's running
2021-09-27T11:20:20Z
Sean Colsen
Search gives no indication that it's running
This is an upstream issue with [MkDocs Material](https://github.com/squidfunk/mkdocs-material).
When performing a search, there is a delay as described in #75. During this delay, the search interface should visually indicate to the use...
This is an upstream issue with [MkDocs Material](https://github.com/squidfunk/mkdocs-material).
When performing a search, there is a delay as described in #75. During this delay, the search interface should visually indicate to the user that a search is in progress. Currently users sometimes get confused and press `Enter` as described in #74
https://lab.civicrm.org/documentation/docs-publisher/-/issues/77
Many issues with poor UX in the search interface
2020-04-26T20:36:00Z
Sean Colsen
Many issues with poor UX in the search interface
This is a general ticket to track progress on multiple, smaller tickets:
* #76
* #75
* #74
* #64
* #70
Most of these are probably upstream issues with [MkDocs Material](https://github.com/squidfunk/mkdocs-material). We should res...
This is a general ticket to track progress on multiple, smaller tickets:
* #76
* #75
* #74
* #64
* #70
Most of these are probably upstream issues with [MkDocs Material](https://github.com/squidfunk/mkdocs-material). We should research and report there.
https://lab.civicrm.org/documentation/docs-publisher/-/issues/78
Allow books to define redirects which point to other books
2017-09-24T00:13:55Z
Sean Colsen
Allow books to define redirects which point to other books
Modify the internal redirect functionality to allow each book to define *external* redirects in the `redirects/internal.txt` file.
(I realize it won't be very intuitive to put external redirects in a file called `internal.txt`, but I th...
Modify the internal redirect functionality to allow each book to define *external* redirects in the `redirects/internal.txt` file.
(I realize it won't be very intuitive to put external redirects in a file called `internal.txt`, but I think it's worth it to live with this unfortunate consequence. In the future we could change the app to first look for a file with a different name.)
https://lab.civicrm.org/documentation/docs-publisher/-/issues/79
Allow multiple guides to be published from within one repository
2021-09-27T11:20:06Z
Sean Colsen
Allow multiple guides to be published from within one repository
In `books/*.yml`, allow a guide to define a subdirectory within the repo that should be used when publishing.
For example, in CiviCRM core, we *might* want to store the Dev Guide, User Guide, and Sysadmin Guide in separate folders with...
In `books/*.yml`, allow a guide to define a subdirectory within the repo that should be used when publishing.
For example, in CiviCRM core, we *might* want to store the Dev Guide, User Guide, and Sysadmin Guide in separate folders within the `docs` directory. This shouldn't be too hard if we just tell `mkdocs` to use a subfolder for its build process.
https://lab.civicrm.org/documentation/docs-publisher/-/issues/80
Editing non-master branches with the pencil icon doesn't work
2017-10-19T15:10:25Z
Sean Colsen
Editing non-master branches with the pencil icon doesn't work
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/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.md
https://lab.civicrm.org/documentation/docs-publisher/-/issues/81
Only publish a guide if the docs within its repo have been changed
2017-10-19T15:15:20Z
Sean Colsen
Only publish a guide if the docs within its repo have been changed
If an extension makes a code change (non-docs), the publisher will still re-publish the guide. When acting on webhook requests, we should look at either the webhook details or the git details to see if any docs files were changed and onl...
If an extension makes a code change (non-docs), the publisher will still re-publish the guide. When acting on webhook requests, we should look at either the webhook details or the git details to see if any docs files were changed and only publish if they were.
CC @Michael_McAndrew
https://lab.civicrm.org/documentation/docs-publisher/-/issues/82
Books without defined versions should get redirects for "stable", and "current"
2017-10-18T21:45:07Z
Sean Colsen
Books without defined versions should get redirects for "stable", and "current"
Reported in this MM thread: https://chat.civicrm.org/civicrm/pl/nt7xmxes4fgk5m45cjcfg17xtc
When a book doesn't define any specific versions we set up one version based on the `master` branch with `latest` in the path. In this situation,...
Reported in this MM thread: https://chat.civicrm.org/civicrm/pl/nt7xmxes4fgk5m45cjcfg17xtc
When a book doesn't define any specific versions we set up one version based on the `master` branch with `latest` in the path. In this situation, we should also set up redirects for `stable`, and `current` that take the reader to `latest`.
Sean Colsen
Sean Colsen
https://lab.civicrm.org/documentation/docs-publisher/-/issues/83
Infinite redirect loop
2017-11-02T16:57:19Z
Sean Colsen
Infinite redirect loop
Not sure why this is happening. If you try going to https://docs.civicrm.org/user/en/4.6/current/email/scheduled-reminders you'll get a redirect error. (Note the incorrect URL with `4.6/current`.)
Looks like the page is redirecting to i...
Not sure why this is happening. If you try going to https://docs.civicrm.org/user/en/4.6/current/email/scheduled-reminders you'll get a redirect error. (Note the incorrect URL with `4.6/current`.)
Looks like the page is redirecting to itself.
```
$ wget 'https://docs.civicrm.org/user/en/4.6/current/email/scheduled-reminders' 2>&1 | grep Location:
Location: /user/en/4.6/current/email/scheduled-reminders [following]
Location: /user/en/4.6/current/email/scheduled-reminders [following]
Location: /user/en/4.6/current/email/scheduled-reminders [following]
Location: /user/en/4.6/current/email/scheduled-reminders [following]
Location: /user/en/4.6/current/email/scheduled-reminders [following]
Location: /user/en/4.6/current/email/scheduled-reminders [following]
Location: /user/en/4.6/current/email/scheduled-reminders [following]
Location: /user/en/4.6/current/email/scheduled-reminders [following]
Location: /user/en/4.6/current/email/scheduled-reminders [following]
Location: /user/en/4.6/current/email/scheduled-reminders [following]
Location: /user/en/4.6/current/email/scheduled-reminders [following]
Location: /user/en/4.6/current/email/scheduled-reminders [following]
Location: /user/en/4.6/current/email/scheduled-reminders [following]
Location: /user/en/4.6/current/email/scheduled-reminders [following]
Location: /user/en/4.6/current/email/scheduled-reminders [following]
Location: /user/en/4.6/current/email/scheduled-reminders [following]
Location: /user/en/4.6/current/email/scheduled-reminders [following]
Location: /user/en/4.6/current/email/scheduled-reminders [following]
Location: /user/en/4.6/current/email/scheduled-reminders [following]
Location: /user/en/4.6/current/email/scheduled-reminders [following]
Location: /user/en/4.6/current/email/scheduled-reminders [following]
```
We should try to change the redirection logic so that a request like this gives a 404 response instead of a 301.
Reported by @wmortada [in Mattermost](https://chat.civicrm.org/civicrm/pl/ehiameh3oin8881s14ciwshsaa)
https://lab.civicrm.org/documentation/docs-publisher/-/issues/84
Upgrade to MkDocs 0.17
2018-02-26T01:03:17Z
Sean Colsen
Upgrade to MkDocs 0.17
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 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.
https://lab.civicrm.org/documentation/docs-publisher/-/issues/85
Peg pip packages to specific versions in the Dockerfile
2018-02-26T01:04:29Z
Sean Colsen
Peg pip packages to specific versions in the Dockerfile
The 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: #84
The 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: #84
https://lab.civicrm.org/documentation/docs-publisher/-/issues/86
Live site should display specific build errors when manually publishing
2021-09-27T11:19:52Z
Sean Colsen
Live site should display specific build errors when manually publishing
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 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/39
book publishing should fail more gracefully when page-building errors are enc...
2018-11-08T04:23:30Z
Sean Colsen
book publishing should fail more gracefully when page-building errors are encountered
*Created by: seanmadsen*
On 2017-02-04 we had a little snafu with the Dev Guide. Here's what happened, chronologically:
1. On 2017-02-03 Michael (at my request) took [these steps](https://github.com/squidfunk/mkdocs-material/issues/...
*Created by: seanmadsen*
On 2017-02-04 we had a little snafu with the Dev Guide. Here's what happened, chronologically:
1. On 2017-02-03 Michael (at my request) took [these steps](https://github.com/squidfunk/mkdocs-material/issues/138#issuecomment-276567696) to install a more bleeding edge version of `pymdown-extensions` in attempt at addressing [civicrm-docs-material#7](https://github.com/civicrm/civicrm-docs-material/issues/7)
1. Shortly thereafter, I made [3 commits](https://github.com/civicrm/civicrm-dev-docs/commits/hooks-op-4), tested them locally with success (with the same version of `pymdown-extensions`), and then pushed them to the `hooks-op-4` branch of `civicrm-dev-docs`.
1. After this push, the docs system attempted to publish the `hooks-op-4` branch but encountered an error that I am fairly certain stemmed from a bug within `pymdown-extensions` and caused by the more bleeding edge version. Unfortunately I have not been able to reproduce this bug locally :slightly_frowning_face:
* The full error output is below
* Most notably: `ERROR - Error building page markdownrules.md`
1. Unfortunately MkDocs didn't handle this error gracefully because it built all the pages up to `markdownrules.md` (as listed in `mkdocs.yml`) and then stopped there without attempting to build any pages listed *after* `markdownrules.md`. (That's too bad, but seems like an upstream issue with MkDocs that we probably can't control so easily.)
* **(Issue A)**: What *would* be good, is if civicrm-docs could *attempt* to build a book, and then only make it live if the build process completes succesfully.
1. The especially bad (and strange) thing that happened here is that *somehow* the `latest` and `master` versions of the Dev Guide also ended up pointing to this botched branch of `hooks-op-4`.
* **(Issue B)**: The errors in publishing one branch ended up messing up another branch. I imagine we should be able to prevent this somehow.
1. Then on 2017-02-04 @ErichBSchulz [pointed out](https://chat.civicrm.org/civicrm/pl/rk56wfjx9bfqbj69hfw6fyfj3c) the problem with the master branch, and I tried to re-publish that branch (without publishing `hooks-op-4`) by loading `https://docs.civicrm.org/admin/publish/dev/en/master`
* **(Issue C)**: publishing the master branch with the URL above didn't work during this time when the Dev Guide was "messed up". I forget the exact error I got when I tried. Either 404 or 500 or 503.
1. Then I asked @bgm to do the following on the server, and these steps got the `master` branch up and running again:
```bash
cd /path/to/civicrm-docs/site
./bin/console docs:publish dev/en/master
```
Again a can't reproduce any of this locally, so I'm not sure how best to proceed here. Hoping that @michaelmcandrew will think of something.
## Full error given by the publishing system
(This was emailed to me)
```text
Running 'mkdocs build -c -f /var/www/civicrm-docs/var/repos/buildfiles/dev.en.master.yml -d /var/www/civicrm-docs/app/../web/static/dev/en/master'
INFO: mkdocs output: '
INFO - Cleaning site directory
INFO - Building documentation to directory: /var/www/civicrm-docs/web/static/dev/en/master
ERROR - Error building page markdownrules.md Traceback (most recent call last):
File "/usr/local/bin/mkdocs", line 11, in sys.exit(cli())
File "/usr/local/lib/python2.7/dist-packages/click/core.py", line 722, in __call__ return self.main(*args, **kwargs)
File "/usr/local/lib/python2.7/dist-packages/click/core.py", line 697, in main rv = self.invoke(ctx)
File "/usr/local/lib/python2.7/dist-packages/click/core.py", line 1066, in invoke return _process_result(sub_ctx.command.invoke(sub_ctx))
File "/usr/local/lib/python2.7/dist-packages/click/core.py", line 895, in invoke return ctx.invoke(self.callback, **ctx.params)
File "/usr/local/lib/python2.7/dist-packages/click/core.py", line 535, in invoke return callback(*args, **kwargs)
File "/usr/local/lib/python2.7/dist-packages/mkdocs/__main__.py", line 156, in build_command ), dirty=not clean)
File "/usr/local/lib/python2.7/dist-packages/mkdocs/commands/build.py", line 379, in build build_pages(config, dirty=dirty)
File "/usr/local/lib/python2.7/dist-packages/mkdocs/commands/build.py", line 332, in build_pages dump_json)
File "/usr/local/lib/python2.7/dist-packages/mkdocs/commands/build.py", line 188, in _build_page site_navigation=site_navigation
File "/usr/local/lib/python2.7/dist-packages/mkdocs/commands/build.py", line 59, in convert_markdown extension_configs=config['mdx_configs']
File "/usr/local/lib/python2.7/dist-packages/mkdocs/utils/__init__.py", line 366, in convert_markdown html_content = md.convert(markdown_source)
File "/usr/local/lib/python2.7/dist-packages/markdown/__init__.py", line 368, in convert self.lines = prep.run(self.lines)
File "/usr/local/lib/python2.7/dist-packages/pymdown_extensions-1.8-py2.7.egg/pymdownx/superfences.py", line 484, in run lines = self.search_nested(lines)
File "/usr/local/lib/python2.7/dist-packages/pymdown_extensions-1.8-py2.7.egg/pymdownx/superfences.py", line 385, in search_nested self.eval(m, start, end)
File "/usr/local/lib/python2.7/dist-packages/pymdown_extensions-1.8-py2.7.egg/pymdownx/superfences.py", line 281, in eval self.process_nested_block(m, start, end)
File "/usr/local/lib/python2.7/dist-packages/pymdown_extensions-1.8-py2.7.egg/pymdownx/superfences.py", line 320, in process_nested_block code = entry["formatter"](self.rebuild_block(self.code), self.lang)
File "/usr/local/lib/python2.7/dist-packages/pymdown_extensions-1.8-py2.7.egg/pymdownx/superfences.py", line 423, in highlight lexer = guess_lexer(self.src) AttributeError: 'SuperFencesBlockPreprocessor' object has no attribute 'src'
```
https://lab.civicrm.org/documentation/docs-publisher/-/issues/21
Change docs system to work with Apache instead of nginx
2018-11-08T04:23:30Z
Sean Colsen
Change 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/20
System to create internal redirects within each book
2018-11-08T04:23:30Z
Sean Colsen
System to create internal redirects within each book
*Created by: seanmadsen*
Within the Developer Guide content migration, a [need](https://github.com/civicrm/civicrm-dev-docs/issues/25) emerged rather quickly to be able to move a page without giving a 404 error to any incoming links. Th...
*Created by: seanmadsen*
Within the Developer Guide content migration, a [need](https://github.com/civicrm/civicrm-dev-docs/issues/25) emerged rather quickly to be able to move a page without giving a 404 error to any incoming links. The docs system should provide a way for each book to specify internal redirects.
MkDocs has [stated](https://github.com/mkdocs/mkdocs/issues/45#issuecomment-234826923) that they want redirection to happen at the server level, so it seems our docs system should be responsible for providing this feature.
For comparison, Read The Docs [offers](http://read-the-docs.readthedocs.io/en/latest/user-defined-redirects.html#page-redirects) this feature. Though, as someone who has never used RTD, reading their description of this feature still leaves me somewhat confused as to the process that content editors must follow to create such redirects.
https://lab.civicrm.org/documentation/docs-publisher/-/issues/18
Home page which gives list of all books in system
2018-11-08T04:23:30Z
Sean Colsen
Home page which gives list of all books in system
*Created by: seanmadsen*
The docs system should provide a welcoming home page at docs.civicrm.org which lists all the books defined in `app/config/books/`.
migrated from [to-do list](https://github.com/civicrm/civicrm-docs/tree/638e...
*Created by: seanmadsen*
The docs system should provide a welcoming home page at docs.civicrm.org which lists all the books defined in `app/config/books/`.
migrated from [to-do list](https://github.com/civicrm/civicrm-docs/tree/638e243c6f4eb06086199e3ea8b529541368f688#to-do).
https://lab.civicrm.org/documentation/docs-publisher/-/issues/17
Create "Administrator Guide" book, separate from User Guide and Developer Guide
2018-11-08T04:23:30Z
Sean Colsen
Create "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/15
Custom theme
2018-11-08T04:23:30Z
Sean Colsen
Custom 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/14
Automatic publishing of extension-specific books, when possible
2018-11-08T04:23:30Z
Sean Colsen
Automatic publishing of extension-specific books, when possible
*Created by: seanmadsen*
should doc infra interact with extension `info.xml` files?
migrated from [to-do list](https://github.com/civicrm/civicrm-docs/tree/638e243c6f4eb06086199e3ea8b529541368f688#to-do).
*Created by: seanmadsen*
should doc infra interact with extension `info.xml` files?
migrated from [to-do list](https://github.com/civicrm/civicrm-docs/tree/638e243c6f4eb06086199e3ea8b529541368f688#to-do).
https://lab.civicrm.org/documentation/docs-publisher/-/issues/87
Documentation: Error 500 returned for bad addresses (should be 404)
2020-04-26T20:34:22Z
AllenShaw
Documentation: 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 Sprint
https://lab.civicrm.org/documentation/docs-publisher/-/issues/88
Live "What is CiviCRM?" doesn't list Backdrop, but Github does list Backdrop
2019-05-16T16:18:09Z
CM Toolan
Live "What is CiviCRM?" doesn't list Backdrop, but Github does list Backdrop
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:/...
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/89
Install google analytics
2020-04-11T14:39:19Z
josh
josh@civicrm.org
Install google analytics
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://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 2019
homotechsual
homotechsual
https://lab.civicrm.org/documentation/docs-publisher/-/issues/90
Notification emails don't have DKIM signature
2020-03-09T15:39:03Z
DaveD
Notification emails don't have DKIM signature
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...
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/16
Book validation during publishing
2019-05-21T10:16:40Z
Sean Colsen
Book 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 2019
homotechsual
homotechsual
https://lab.civicrm.org/documentation/docs-publisher/-/issues/13
Find a more usable web-based UI for simple editing
2019-05-21T10:16:19Z
Sean Colsen
Find 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 2019
homotechsual
homotechsual
https://lab.civicrm.org/documentation/docs-publisher/-/issues/11
auto-generate PDF / epup versions
2019-07-18T08:55:06Z
Sean Colsen
auto-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 2019
homotechsual
homotechsual
https://lab.civicrm.org/documentation/docs-publisher/-/issues/91
Move developer training guide from wiki to docs
2019-10-07T10:03:11Z
gibsonoliver
Move developer training guide from wiki to docs
https://lab.civicrm.org/documentation/docs-publisher/-/issues/92
Improve documentation of APIs
2019-10-07T09:38:45Z
gibsonoliver
Improve documentation of APIs
https://lab.civicrm.org/documentation/docs-publisher/-/issues/93
Make developer docs more accessible to new Civi developers
2019-10-07T10:01:05Z
gibsonoliver
Make developer docs more accessible to new Civi developers
https://lab.civicrm.org/documentation/docs-publisher/-/issues/12
seperate repo for app/config/books
2019-07-17T08:28:03Z
Sean Colsen
seperate 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 2019
homotechsual
homotechsual
https://lab.civicrm.org/documentation/docs-publisher/-/issues/9
apply navbar auto-scrolling to all docs guides
2017-01-31T06:17:39Z
Sean Colsen
apply navbar auto-scrolling to all docs guides
*Created by: seanmadsen*
In the Dev Guide, these two PRs: [#39](https://github.com/civicrm/civicrm-dev-docs/pull/39) and [#42](https://github.com/civicrm/civicrm-dev-docs/pull/42) made a UX improvement by automatically scrolling the lef...
*Created by: seanmadsen*
In the Dev Guide, these two PRs: [#39](https://github.com/civicrm/civicrm-dev-docs/pull/39) and [#42](https://github.com/civicrm/civicrm-dev-docs/pull/42) made a UX improvement by automatically scrolling the left navigation bar to the active element, when necessary. We should restructure this tweak so it is a shared resource, applied to all guides that live within civicrm-docs. A simple approach could be referencing one js file. A more sophisticated approach would be creating a custom theme that is used by all guides.
https://lab.civicrm.org/documentation/docs-publisher/-/issues/94
All doc links are broken
2020-04-11T13:55:18Z
dschafer
All doc links are broken
Links 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/95
Implement cookie consent on docs.civicrm.org
2021-09-27T11:18:46Z
homotechsual
Implement cookie consent on docs.civicrm.org
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.
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.
homotechsual
homotechsual
2020-04-30
https://lab.civicrm.org/documentation/docs-publisher/-/issues/96
Overhaul the docs "front page".
2021-09-27T08:10:11Z
homotechsual
Overhaul 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/
homotechsual
homotechsual
2020-05-17
https://lab.civicrm.org/documentation/docs-publisher/-/issues/8
switch from symfony/yaml to the php yaml extension for yaml processing
2017-02-14T09:19:21Z
Sean Colsen
switch from symfony/yaml to the php yaml extension for yaml processing
*Created by: michaelmcandrew*
symfony/yaml doesn't support all yaml formatting (only a subset that is useful for configuration files).
switching to php's yaml extension should give us more robust support (and amongst other things) al...
*Created by: michaelmcandrew*
symfony/yaml doesn't support all yaml formatting (only a subset that is useful for configuration files).
switching to php's yaml extension should give us more robust support (and amongst other things) allow people to write yaml comments that start at the beginning of the line.
https://lab.civicrm.org/documentation/docs-publisher/-/issues/5
"Improve documentation" section: Page not found in the "currently shifting" l...
2016-06-28T10:30:57Z
Sean Colsen
"Improve documentation" section: Page not found in the "currently shifting" link.
*Created by: klonos*
It points to `https://civicrm.org/blog/michael-mcandrew/moving-civicrms-user-and-administrator-guide-gitbook-or-readthedocs` - should point to this instead:
https://civicrm.org/blog/michael-mcandrew/moving-civicrms-...
*Created by: klonos*
It points to `https://civicrm.org/blog/michael-mcandrew/moving-civicrms-user-and-administrator-guide-gitbook-or-readthedocs` - should point to this instead:
https://civicrm.org/blog/michael-mcandrew/moving-civicrms-user-and-administrator-guide-to-gitbook-or-readthedocs
(there's a missing "to" before the word "gitbook")
@michaelmcandrew @totten, This was more of an issue with the website rather than with documentation itself, but the issue queue for the https://github.com/civicrm/civicrm-website-org repo is not enabled. What is the best way to notify you guys of such issues?
https://lab.civicrm.org/documentation/docs-publisher/-/issues/97
Fix google listing
2021-09-27T11:19:36Z
Stoob
Fix google listing
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.** 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/98
Searching matches partial but not complete word in some cases
2021-09-27T08:07:27Z
Rich
Searching matches partial but not complete word in some cases
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/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/99
Publishing no longer working
2022-02-09T17:14:27Z
jensschuppe
Publishing no longer working
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 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/100
Docs falling off organic search results
2022-05-25T16:34:56Z
josh
josh@civicrm.org
Docs falling off organic search results
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 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.
homotechsual
homotechsual
2022-04-29
https://lab.civicrm.org/documentation/docs-publisher/-/issues/101
Remove author from Docs Books
2022-09-12T05:48:49Z
homotechsual
Remove 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!
homotechsual
homotechsual
2022-08-31
https://lab.civicrm.org/documentation/docs-publisher/-/issues/102
Refactor Version and Language handling.
2023-07-27T15:48:44Z
homotechsual
Refactor 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`.*
homotechsual
homotechsual
https://lab.civicrm.org/documentation/docs-publisher/-/issues/103
Documentation contains discriminatory example
2023-03-31T12:56:00Z
katharina.u
Documentation contains discriminatory example
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/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'
)