Question: How to override the new default sort on articles?

gangstR commented 3 weeks ago

I was in the process of rebuilding the dev pkgdown site for a new release of a package within my company and noticed two things that seemed to have broken:

My _pkgdown.yml file I've used for more than two years to order the articles was not respected. Articles were sorted based on filename despite the structure.
Even after making some name adjustments to achieve my desired sort, all attempts to use the separator (i.e., text: -------) on the menu between article types (e.g., how-to sections, in-depth tech sections, etc.) failed. I'm unable to get any menu separator to show up.

I took a long pause and read the CHANGELOG and saw that #2253 had been implemented to change the article default sort. But, alas, I must be missing it, but I can't find any information on how to override that behavior. Secondly, there is no discussion of the separator being removed (still shown in examples in the docs). A default sort would inherently obviate the use of the separator, so perhaps understanding how to override the default new sort behavior will fix my second issue? While I'm still looking at this, I reinstalled pkgdown back to the last commit just prior to the patch ff2df8d, and I found that everything worked as expected. So, I seem to be in the neighborhood 😺

I appreciate you! Thank you

hadley commented 3 weeks ago

That just sounds like a bug. Can you provide a simple reprex, or failing that a link to your package?

gangstR commented 2 weeks ago

As a gangstR, I live my life without freedom behind corporate bars, so I'm not able to exchange things on the inside with people on the outside. [My apologies for a bit of levity...] But I did do some investigation. I pulled down the ymlthis package from GitHub. It's kind of old, so I rebuilt the docs first and then the pkgdown site:

Attempt at reprex:

devtools::document()
pkgdown::build_site(devel = FALSE, new_process = FALSE, examples = FALSE)

Things look great with the finished local site build (just a couple of minor complaints to update bootstrap, etc.)

Note, the ymlthis package had the following articles section:

    articles:
      text: Articles
      menu:
      - text: An Introduction to ymlthis
        href: articles/introduction-to-ymlthis.html
      - text: The YAML Fieldguide
        href: articles/yaml-fieldguide.html
      - text: 'YAML: an Overview'
        href: articles/yaml-overview.html

I then proceeded to change the article listing order (which was coincidentally already in alphabetic order). I shuffled them and added separators, then rebuilt.

Here are changes I made:

    articles:
      text: Articles
      menu:
      - text: 'YAML: an Overview'
        href: articles/yaml-overview.html
      - text: -------
      - text: An Introduction to ymlthis
        href: articles/introduction-to-ymlthis.html
      - text: -------
      - text: The YAML Fieldguide
        href: articles/yaml-fieldguide.html

Surprise! Everything worked. I was puzzled. I reviewed the ymlthis _pkgdown.yml file against my own and noticed that the ymlthis author has a section I do not have in any of my packages:

articles:
- title: All vignettes
  desc: null
  contents:
  - '`introduction-to-ymlthis`'
  - '`yaml-fieldguide`'
  - '`yaml-overview`'

So, I removed that section and rebuilt the site a third time. Sure enough, articles immediately moved to an alphabetic sort and the separators vanished --- exactly what I'd observed in my own site.

I've not had the above section in any of my dozen or so packages in the last few years, but it seems the patch I referenced in my initial post has made this section essential if you want to be able to make changes such as those in this reprex.

Is this helpful? I apologize that I'm unable to share an internal example, but hopefully this is practical enough to follow.

Thank you

hadley commented 2 weeks ago

Oh interesting, it looks like you're primarily using the oldest way of controlling the menu bar, where you have to explicitly control everything. A few versions ago we released something article specific, which is easier to use (and I'd recommend you switch to). But your manual customisation should still win, so I'll have a look.

hadley commented 2 weeks ago

@gangstR thanks for reporting this! It turns out I accidentally introduced a rather serious bug that would have affected a bunch of sites. So I really appreciate you trying out the dev version and reporting it 😄

r-lib / pkgdown

Question: How to override the new default sort on articles? #2673