Docs Publisher issueshttps://lab.civicrm.org/documentation/docs-publisher/-/issues2017-04-30T22:16:43Zhttps://lab.civicrm.org/documentation/docs-publisher/-/issues/34Force a standard set of markdown extensions to be enabled for all books2017-04-30T22:16:43ZSean ColsenForce a standard set of markdown extensions to be enabled for all books*Created by: seanmadsen*
There are some markdown extensions that we basically just want to be enabled all the time, even if each book's `mkdocs.yml` file doesn't enable them. I think we should force them to be enabled at [this point in ...*Created by: seanmadsen*
There are some markdown extensions that we basically just want to be enabled all the time, even if each book's `mkdocs.yml` file doesn't enable them. I think we should force them to be enabled at [this point in the code](https://github.com/civicrm/civicrm-docs/blob/master/src/AppBundle/Utils/Publisher.php#L103).
It should set the following:
```yaml
markdown_extensions:
- attr_list
- admonition
- codehilite
- toc(permalink=true)
- pymdownx.superfences
- pymdownx.inlinehilite
- pymdownx.tilde
- pymdownx.betterem
```
More details within [Material's docs](http://squidfunk.github.io/mkdocs-material/extensions/pymdown/)https://lab.civicrm.org/documentation/docs-publisher/-/issues/33How will users switch between different versions of a book?2017-04-30T22:16:43ZSean ColsenHow 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/32Migrating content from stack exchange to docs2017-04-30T22:16:43ZSean ColsenMigrating 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/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/28Home page - books missing2017-04-30T22:16:43ZSean ColsenHome page - books missing*Created by: seanmadsen*
In my local installation of civicrm-docs I see a home page which lists the User Guide but does not list the Dev Guide. When I publish all books via command line the Dev Guide is include in this publishing proces...*Created by: seanmadsen*
In my local installation of civicrm-docs I see a home page which lists the User Guide but does not list the Dev Guide. When I publish all books via command line the Dev Guide is include in this publishing process, so the app is well aware of the existence of the Dev Guide. Tim also [observed](https://chat.civicrm.org/civicrm/pl/7fh9y7w5o7d458yukjsuf33mby) the same behavior. https://lab.civicrm.org/documentation/docs-publisher/-/issues/27Home page - improve visual style2017-04-30T22:16:43ZSean ColsenHome 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/26home page - add some more info about docs, generally2017-04-30T22:16:43ZSean Colsenhome page - add some more info about docs, generally*Created by: seanmadsen*
If we want to redirect civicrm.org/documentation to docs.civicrm.org eventually, we'll need some more info on the docs home page.
Michael [said](https://github.com/civicrm/civicrm-docs/issues/18#issuecomment...*Created by: seanmadsen*
If we want to redirect civicrm.org/documentation to docs.civicrm.org eventually, we'll need some more info on the docs home page.
Michael [said](https://github.com/civicrm/civicrm-docs/issues/18#issuecomment-273431305) It does need a bit of fleshing out. Copying content from http://civicrm.org/documentation to https://github.com/civicrm/civicrm-docs/blob/master/src/AppBundle/Resources/views/Read/home.html.twig https://lab.civicrm.org/documentation/docs-publisher/-/issues/25Clarify role (user / admininstrator / developer) terminology2017-04-30T22:16:43ZSean ColsenClarify role (user / admininstrator / developer) terminology*Created by: michaelmcandrew*
The words user and developer are pretty clear.
Administrator is ambigious since it can refer to
* an advanced user that sets things up for other users using the UI
* a system administrator that doe...*Created by: michaelmcandrew*
The words user and developer are pretty clear.
Administrator is ambigious since it can refer to
* an advanced user that sets things up for other users using the UI
* a system administrator that does stuff like install, host, and is familiar with CLI, SSH, FTP, DNS, etc.
I'm not sure that coming up with a rule like "administrator MUST only be used to signify system administrator" is a good idea since language is nuanced. On the other hand, if we could could up with an acceptable phase for an "advanced user that does set up" that might change my mind.
Alternatively, just some sensible guidance on how we refer to different roles would be good to have in the documentation guidelines.https://lab.civicrm.org/documentation/docs-publisher/-/issues/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/21Change docs system to work with Apache instead of nginx2018-11-08T04:23:30ZSean ColsenChange docs system to work with Apache instead of nginx*Created by: seanmadsen*
@michaelmcandrew and I talked on Mattermost yesterday about the steps needed to implement [internal redirects](https://github.com/civicrm/civicrm-docs/issues/20) for each book, which is a high-priority issue, sl...*Created by: seanmadsen*
@michaelmcandrew and I talked on Mattermost yesterday about the steps needed to implement [internal redirects](https://github.com/civicrm/civicrm-docs/issues/20) for each book, which is a high-priority issue, slowing the progress of content migration within the Developer Guide. Michael recommended that switching the server from nginx to Apache would make this internal redirects project easier. This issues requires changes within the docs app so that it runs reliably on Apache, including reading and [manual publishing via URL](https://github.com/civicrm/civicrm-docs#manual-publishing). https://lab.civicrm.org/documentation/docs-publisher/-/issues/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/17Create "Administrator Guide" book, separate from User Guide and Developer Guide2018-11-08T04:23:30ZSean ColsenCreate "Administrator Guide" book, separate from User Guide and Developer Guide*Created by: seanmadsen*
We currently have a User Guide and a Developer Guide. The addition of an Administrator Guide would round out the documentation and cover topics such as installing/updating core, finding/installing extensions, ...*Created by: seanmadsen*
We currently have a User Guide and a Developer Guide. The addition of an Administrator Guide would round out the documentation and cover topics such as installing/updating core, finding/installing extensions, and basic troubleshooting. Some of this content is currently in the User Guide (e.g. [here](https://docs.civicrm.org/user/en/stable/initial-set-up/installation-and-basic-set-up/)) and some of it is in the wiki (e.g. [here](https://wiki.civicrm.org/confluence/display/CRMDOC/Installation+and+Upgrades)).
migrated from [to-do list](https://github.com/civicrm/civicrm-docs/tree/638e243c6f4eb06086199e3ea8b529541368f688#to-do).https://lab.civicrm.org/documentation/docs-publisher/-/issues/16Book validation during publishing2019-05-21T10:16:40ZSean ColsenBook validation during publishing*Created by: seanmadsen*
Perform some simple validation steps when publishing a book.
For example `ack '\!\[.*\]\((.*?)( ".*)?\)' -h --nobreak --output='$1'` will give all images. We can check whether they exist.
migrated from [...*Created by: seanmadsen*
Perform some simple validation steps when publishing a book.
For example `ack '\!\[.*\]\((.*?)( ".*)?\)' -h --nobreak --output='$1'` will give all images. We can check whether they exist.
migrated from [to-do list](https://github.com/civicrm/civicrm-docs/tree/638e243c6f4eb06086199e3ea8b529541368f688#to-do).Docs Publisher 2019homotechsualhomotechsualhttps://lab.civicrm.org/documentation/docs-publisher/-/issues/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/14Automatic publishing of extension-specific books, when possible2018-11-08T04:23:30ZSean ColsenAutomatic 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/13Find a more usable web-based UI for simple editing2019-05-21T10:16:19ZSean ColsenFind a more usable web-based UI for simple editing*Created by: seanmadsen*
find a nice user-friendly UI for people to edit the documentation (the github UI is OK but we can do better)
migrated from [to-do list](https://github.com/civicrm/civicrm-docs/tree/638e243c6f4eb06086199e3ea8b...*Created by: seanmadsen*
find a nice user-friendly UI for people to edit the documentation (the github UI is OK but we can do better)
migrated from [to-do list](https://github.com/civicrm/civicrm-docs/tree/638e243c6f4eb06086199e3ea8b529541368f688#to-do).Docs Publisher 2019homotechsualhomotechsual