Docs Publisher issueshttps://lab.civicrm.org/documentation/docs-publisher/-/issues2020-04-11T14:39:19Zhttps://lab.civicrm.org/documentation/docs-publisher/-/issues/89Install google analytics2020-04-11T14:39:19Zjoshjosh@civicrm.orgInstall google analyticsWe're currently only tracking the property associated with civicrm.org and would like to see user behavior for docs.civicrm.org. Tracking data below:
```
<!-- Global site tag (gtag.js) - Google Analytics -->
<script async src="https://w...We're currently only tracking the property associated with civicrm.org and would like to see user behavior for docs.civicrm.org. Tracking data below:
```
<!-- Global site tag (gtag.js) - Google Analytics -->
<script async src="https://www.googletagmanager.com/gtag/js?id=UA-1370005-4"></script>
<script>
window.dataLayer = window.dataLayer || [];
function gtag(){dataLayer.push(arguments);}
gtag('js', new Date());
gtag('config', 'UA-1370005-4');
</script>
```Docs Publisher 2019homotechsualhomotechsualhttps://lab.civicrm.org/documentation/docs-publisher/-/issues/60Automatic publishing for books hosted in GitLab2019-05-21T10:18:44ZSean ColsenAutomatic publishing for books hosted in GitLab*Created by: seanmadsen*
We can automatically publish books when changes are made, but only if the book is hosted on GitHub (and if the owner configures the webhooks correctly). It'd be great to get something like this working for GitLa...*Created by: seanmadsen*
We can automatically publish books when changes are made, but only if the book is hosted on GitHub (and if the owner configures the webhooks correctly). It'd be great to get something like this working for GitLab too, so that we can automatically publish books which are hosted in GitLab.michaelmichaelhttps://lab.civicrm.org/documentation/docs-publisher/-/issues/54Implement "watchers" email addresses in book config files2017-04-30T22:16:43ZSean ColsenImplement "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/50Allow book versions to be defined in a more flexible way2017-10-19T14:59:04ZSean ColsenAllow 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/38"watch page" feature2017-04-30T22:16:43ZSean 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/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/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/24The "Publishing" email notificiations should include commit messages2017-10-12T14:36:37ZSean ColsenThe "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. michaelmichaelhttps://lab.civicrm.org/documentation/docs-publisher/-/issues/23"Edit on GitHub" should take user to specific page2017-04-30T22:16:43ZSean 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/22Provide language and version switching capability within books2017-04-30T22:16:43ZSean ColsenProvide 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/20System to create internal redirects within each book2018-11-08T04:23:30ZSean ColsenSystem 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/18Home page which gives list of all books in system2018-11-08T04:23:30ZSean ColsenHome 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/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/12seperate repo for app/config/books2019-07-17T08:28:03ZSean Colsenseperate repo for app/config/books*Created by: seanmadsen*
create a seperate repo for app/config/books where we can define books independently of this repo
migrated from [to do list](https://github.com/civicrm/civicrm-docs/tree/638e243c6f4eb06086199e3ea8b529541368f68...*Created by: seanmadsen*
create a seperate repo for app/config/books where we can define books independently of this repo
migrated from [to do list](https://github.com/civicrm/civicrm-docs/tree/638e243c6f4eb06086199e3ea8b529541368f688#to-do)Docs Publisher 2019homotechsualhomotechsualhttps://lab.civicrm.org/documentation/docs-publisher/-/issues/9apply navbar auto-scrolling to all docs guides2017-01-31T06:17:39ZSean Colsenapply 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.