Docs Publisher issueshttps://lab.civicrm.org/documentation/docs-publisher/-/issues2016-06-28T10:30:57Zhttps://lab.civicrm.org/documentation/docs-publisher/-/issues/5"Improve documentation" section: Page not found in the "currently shifting" l...2016-06-28T10:30:57ZSean 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/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. https://lab.civicrm.org/documentation/docs-publisher/-/issues/8switch from symfony/yaml to the php yaml extension for yaml processing2017-02-14T09:19:21ZSean Colsenswitch 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/63Move this repo to GitLab2017-04-30T22:16:43ZSean ColsenMove 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/62Re-title wiki.civicrm.org so Docs site is preferred2017-04-30T22:16:43ZxurizaemonRe-title wiki.civicrm.org so Docs site is preferredCurrently 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/56Say "guides" instead of "books"2017-04-30T22:16:43ZSean ColsenSay "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/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/44remove docs:serve command2017-04-30T22:16:43ZSean Colsenremove 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/42Set up theme customizations2017-04-30T22:16:43ZSean ColsenSet up theme customizations*Created by: seanmadsen*
*Created by: seanmadsen*
https://lab.civicrm.org/documentation/docs-publisher/-/issues/40better CSS for definition lists2017-04-30T22:16:43ZSean Colsenbetter 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 morehttps://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/36How do we include theme customizations in this repo?2017-04-30T22:16:43ZSean ColsenHow 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/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