Cell names do not show in document outline (VSCode)

[nickriches]

Cell names are really useful for navigating. By this I mean

CODE

This works well in RStudio to help navigate to relevant code cells/chunks. However, I have not found a way to do this in Quarto when using VSCode. When I view the outline the names of code cells do not appear.

[jjallaire]

Thanks for this, we are hoping to make some big improvements in outlining/indexing over the next few months and will make code blocks part of this.

[nickriches]

Excellent - thanks! 😊

[promicrobial]

This would be a super nice feature to have! I've been making do with creating subheadings for different code chunks.

[renatovargas]

Thank you for this. I'm coming from posit-dev/positron#3822 and was instructed to bring it up here instead.

Not an issue, but a shameless request related to this. Great work btw. For Quarto documents (.qmd), RStudio shows only headings and subheadings in the outline, like you can see below on the left. Positron (and now I know VSCode), on the other hand, shows headings, subheadings and (code cell) like you can see on the right. Now this looks great for defined code chunk listings that are named for cross refs, but very crowded for the rest of unnamed code chunks.

I am aware that you can click on "collapse all" like below, but that will collapse to first level headings only and you lose some ability to quickly navigate the document, especially in this case, where you go back and forth, perhaps trying out different elasticities in a very specific subsection to see poverty results at the end or going back to see how you set something up. I am aware also that you can individually open up each heading.

Now, I'm not saying to get rid of "(code cell)", because it encourages you to name your chunks and it's a superb feature, but I would appreciate it if there was perhaps a "toggle code cells" option, independent from collapse/expand for the Outline panel, so that you could limit it to headings and subheadings in Rmd, qmd's and other document type files. Thank you.

[artmg]

Returning to the main issue of code cells appearing in the Outline and breadcrumbs as (code cell), I just wanted to observe that the VScode feature 'Sticky Header on Scroll' does correctly capture code cell boundaries and their name (even if it makes no attempt to parse the name from the line) as shown here:

You can see both 12 R markdown and 22 cars are in the white-backgrounded sticky zone at the top of the editor window above.

I do not know if that bears any relation to the Outline symbol gathering mechanism, but it does at least give a useful addition to the breadcrumb if you want to know what is the name of the code cell you are currently editing in.

As another diagnostic input to this issue, @renatovargas I know that you'd rather not see them at all, because you prefer the RStudio Outline-style navigation on the right to the statusbar navigation at the bottom...

...however I notice in your issue screenshot you had some code cells which were named and some that weren't

Perhaps it might help diagnose this issue if you could please share why the first three chunk names, lst-* show names here yet the next three just show (code cell) - thanks.

Oh, and if you DO want people to seriously consider adding the feature you mention in your comment above, it might be best if you raise it as a separate issue thread, so that it does not get lost in this conversation.

[renatovargas]

Thank you for raising these questions @artmg.

As another diagnostic input to this issue, renatovargas I know that you'd rather not see them at all, because you prefer the RStudio Outline-style navigation on the right to the statusbar navigation at the bottom...

Oh, I do like those references to code chunks (and Positron's position of the outline too), but I would want to have the option to toggle them on and off (with a tick box) independently of hierarchy expand/collapse level because the unnamed ones make it too crowded when expanded, and I like to navigate to subheadings easily without that clutter if I so choose. However, if all of a sudden I want to go to a specific code chunk, I would just toggle them on, and boom, I'm there.

...however I notice in your issue screenshot you had some code cells which were named and some that weren't. Perhaps it might help diagnose this issue if you could please share why the first three chunk names, lst-* show names here yet the next three just show (code cell) - thanks.

Sure, that is not arbitrary. The ones that are named were specifically labeled using hash-pipe YAML comments to be able to cross reference to them from the narrative. I did not name the ones I didn't need to cross-reference. Just make sure you don't mix hash-pipe comments with inline ones like {r eval=FALSE}. Stick to the former in Positron #| eval: false because of this: posit-dev/positron#4104 (comment). This is a quarto document, but I understand that this affordance comes from Pandoc, so you should be fine doing this in Rmd files too. Don't quote me on this last point, though. I assume it's a good habit to label all of them.

For example, for the first named item in the screenshot you are quoting, the code looks like the code below (disregard the # end of chunk at the end, which is there for the clossing ticks to render in this example).

```{r}
#| label: lst-zone-data

zone_data <- hh %>% 
  select(household_id, hh_01_code, hh_02, hh_03, marz) %>% 
  rename(
    household_id  = household_id, # Household id
    settlement    = hh_01_code,   # Settlement
    marz_no       = hh_02,        # Marz
    urban_rural   = hh_03         # 1 = urban, 2 = rural
  )
```  # end of chunk

The first chunk in the image that has no name afterwards (code cell) has no such hash pipe YAML label. I hope that helps.

Oh, and if you DO want people to seriously consider adding the feature you mention in your comment above, it might be best if you raise it as a separate issue thread, so that it does not get lost in this conversation.

Well, I think that beggars can't be choosers. We already get so much for free that I would feel bad being pushy. I brought it up somewhere else and was instructed to add it here instead by Julia because this thread consolidates several related functionalities and this issue is still open, so let's be patient with the team.

[artmg]

ahhh, so the neater alternative to @promicrobial 's workaround of adding additional subheading above the code blocks would be to insert a 'hash pipe label' just inside the code block, such as

#| label: cars

to correctly label the code cell 'cars', thus, in both the outline and the breadcrumbs

or if one felt compelled to abide by quarto list cross-referencing standards for code blocks then #| label: lst-cars.

This hash pipe label workaround appears to give the closest approximation to the outline authors might hope for, and as R and other execution environments will treat the hash pipe as a label, it is otherwise transparent

Thanks for this great tip @renatovargas

As to your 'getting things for free' comment, please bear in mind that the gratis nature of libre open-source is strongly supported by voluntary community effort. Your personal time commitment to reporting and updating guides both users and developers. Participating positively on issues like this is making more of a difference than you might realise in driving projects like this forward. You are paying with your time, which some people see as more precious than currency, so it's worth remembering that morally you one of the net positive contributors here 😃