Ordered tours doesn't work

[davidgs]

I am trying to link a series of tours in a single repository and no amount of naming conventions seem to work.

From the docs:

nextTour - The title of the tour that this tour is meant to precede.

I've set that in each .tour file, but it is never honored. Each tour, after being run, ends with Finish Tour with no option to go to the next tour.

So then:

Linking Tours
If you want to create a series of tours, that a user can navigate through in sequence, then simply prefix your tour title's with the number they represent in the tour order (e.g. 1: Foo, 2 - Bar). When your tours are titled like this, the tour player will automatically provide the following benefis to your readers:

If the current tour has a subsequent tour, then it's final step will display a Next Tour link instead of the Finish Tour link. This allows users to easily jump to the next tour.

If the current tour has a previous tour, then it's first step will display a Previous Tour link. This allows users to navigate back to the tour they might have just navigated from.

If you don't want to number your tours like this, but you'd still link to link one tour to another, you can open it's *.tour file and set the nextTour property to the title of the tour you'd like it to link to.

I've tried this approach too, without success. It is unclear whether I should use the title field in the previous tour's nextTour field, or the name of the file, but I've tried every iteration without any noticeable effect.

What am I missing? Or does this not work?

[atrnh]

I have this issue too — just like @davidgs, I've tried using the # - <title> naming convention and setting the nextTour property. Neither work: at the end of a tour, I see a Finish Tour link instead of a Next Tour one.

Edit: I should probably mention that I'm using Insiders 😅 Haven't tried any of this with the stable build.

[kazemicode]

The nextTour property does not work for me either. However, I was able to use the format of #1 - Title here to successfully order and link my tours. Omitting the # does not work, which makes the docs that @davidgs quoted above incorrect.

[lostintangent]

Something must have broken here 🤔 Let me take a look.

[peter-kehl]

First:
I confirm that Next Tour and Previous Tour auto-linking does work (without using nextTour attribute), but I've tested it only on the current main (1ef66d7). It's likely to work on v.0.0.59. Unsure about v.0.0.58 from Marketplace - see #260.

Second:
(As of v.0.0.59) auto-linking works only if:

1. Tour titles are in format `number - some text...", and
2. The separator between the number and the rest of the title is - (space, dash, space). For example, number_some text... or number some text... do not work. And
3. The number doesn't have any leading zero(s), and
4. The tour numbers start from 1, and are consecutive (1 - intro will not auto-link to 3 - assignment, even though there is no 2 - ...).

Third:
Request of relaxation of the above restrictions. Following are the reasons (in order close to the order of restrictions listed above):

1. (And #2 from the above, too) People may want the tour titles to be in different format, for example exact same as tour file names, so if they see the tour title under CODETOUR treeview, they can locate its file easily. And many people prefer filenames without spaces (so that they don't have to quote/escape them in shell...).
   Hence, please allow the number to be followed by just a space, underscore, dot... (before the rest of the title). Also, allow:
2. Leading zero(s).
   I have a repository with 17+ examples, and I'd like a tour for each. To have them ordered in file lists, VS Code navigator..., I prefix their folder names numbers. Folders for examples 1-9 I prefix with a leading zero. If numbers went up to three digits, I'd add up to two zeros. Wouldn't it help to be consistent, and have the same for tour titles?
3. Also start from 0 (or 00, 000...).
   The same project has folders 00_utils/ and 00_test_harness/, and I'd like to have tour titles reflect them.
4. Start from from any (lowest) number - but not necessarily 0, 00... nor 1, 01... And:
5. Follow to the next higher number - but not necessarily consecutive.
   Why?
   • People may have a list of tours. Then they remove the very first tour, but don't want to rename the rest (because of links/references...). Or
   • They remove tours in-between, but they want the flow to stay. Or
   • They actually plan tour numbers as non-consecutive for some other reason. In my project mentioned above, I want several tours for the 00_utils/ and 00_test_harness/, so I prefix the tours with 001, 002, 003... But I want only one tour for each of the rest of the folders (01_xxx/, 02_xxx/...), so I prefix those with 010, 020, 030...

[jamiebarrow]

Yeah it took me a while as well to realize that only the title without the numbering is used when linking.

If the CodeTour side panel shows the tour as "1 - Newcomer Onboarding" then you would use [Newcomer Onboarding] to link to it and not [1 - Newcomer Onboarding], similarly I've sometimes included punctuation in my title and ended up just renaming it to only have text, e.g. "2 - Some heading - some sub-title" doesn't appear to be linkable, but "2 - Some subtitle for some heading" does with [Some subtitle for some heading]