Explain what conditions must be met to show hover icon to create issue behind tasklist items

[HonkingGoose]

Code of Conduct

• I have read and agree to the GitHub Docs project's Code of Conduct

What article on docs.github.com is affected?

https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/about-task-lists

What part(s) of the article would you like to see updated?

The docs say:

If a task requires further tracking or discussion, you can convert the task to an issue by hovering over the task and clicking button-icon-here in the upper-right corner of the task.

The docs don't explain if there are any rules you need to follow to allow GitHub to show that hover icon, like:

• only put issue or PR link after the tasklist
• don't use special characters like ( or )
• don't do ...

Or maybe this is a "rights" issue where you need a certain level of access to the repository before you see that button?

Additional information

Why I'm asking about any possible rules: @viceice (maintainer of the repository) is not seeing the hover icon behind items in their tasklist:

• Validate download checksums if possible containerbase/base#875

With the current docs I can't determine if this is:

• bad formatting of the tasklist
• a problem with access rights to the repository
• bug in GitHub

---

Update from a maintainer

Content change suggested to fix this issue

We need to make it clearer to users how to convert a tasklist item to an issue. We'll do this by adding a brief new section to the article About task lists.

1. After the section "Reordering tasks", add a new heading level 2 "Converting tasks into issues".
2. Add a brief explanation of how to convert a task into an issue.
3. Add the following screenshot to the folder for images about writing: https://github.com/github/docs/tree/main/assets/images/help/writing.
   
4. Include the image below the explanation and make sure you add suitable alt text (see Images).

You may find it useful to look at the alt text for other images on the page for inspiration, for example:

docs/content/get-started/writing-on-github/working-with-advanced-formatting/about-task-lists.md

Line 64 in 275f369

{% ifversion fpt or ghec %} {% endif %}

[cmwilson21]

👋 @HonkingGoose Thanks so much for opening an issue! And thanks for the extra context and providing the example case.

I'll triage this for the team to take a look 👀

[omerbensaadon]

Hey @HonkingGoose, PM here, I would recommend you use the new tasklists as they are meant to replace this version and resolve many of the UX sharp edges you're running into :)

[HonkingGoose]

Hi @omerbensaadon, thanks for responding!

New tasklists look nice

Reading the docs for the new tasklists, it looks nice! The waitlist only accepts organization level accounts to try the feature though, so I can't test it on my personal account. I'll have to wait for it to become public before I can try it. 😄

Future enforcement of full links in all body text on GitHub?

I see that tasklists items must use a full link to issues/pull requests. Here's the quote, I bolded the relevant part:

4. For each item you want to add to your tasklist, type - [ ] on a new line, followed by a space, and either a link to an issue, a link to a pull request, or some text to create a draft issue.
   • You must provide a full link to an issue or pull request. For example, https://github.com/octo-org/octo-repo/issues/45.

I remember GitHub removed the #45 shorthand-syntax a while ago, which was quickly reverted, because the change broke every old link that used the shorhand-syntax. 😄

In the docs I see the new UI has search built in, where you can select the issue you want with the Enter key. I wonder if this change is to prepare for a more general enforcement of using full links? That way GitHub could eventually drop support for the shorthand? Is there anything you can tell me about that @omerbensaadon?

[omerbensaadon]

Oh that's not actually true, you can totally use the shorthand or full URLS with new tasklists. Can you link me to where you found that?

[HonkingGoose]

@omerbensaadon Here's where I found the text: https://docs.github.com/en/issues/tracking-your-work-with-issues/about-tasklists#creating-tasklists-with-markdown, search for full link. That same page also shows a "finished tasklist" that only uses the full link:

### My tasks
- [ ] https://github.com/octo-org/octo-repo/issues/45
- [ ] Draft issue title

[omerbensaadon]

Gotcha, I'll submit an edit to that doc which shows a shorthand link to make it clearer we can accept both

[felicitymay]

Hi @HonkingGoose

I was checking through open issues and wondered if this one is now resolved.

I can see that you've worked with another Hubber to improve the documentation for the new tasklists - thank you 💖

Is there anything else we should consider before we close this issue?

[HonkingGoose]

@felicitymay the docs for the current iteration of task lists are still lacking information.

But if the plan is that everyone migrates to the new task lists that's in beta, we would need to check those docs.

So the short answer is: I don't really know. 🙂

[felicitymay]

Hi @HonkingGoose - apologies for dropping the ball on this issue 😞

Using a test account that doesn't have access to the private beta for task lists, I copied in some of the text from the issue that you linked in your summary above. As far as I can tell, there is no problem with your syntax and this ought to work as expected for anyone who has access to create issues. The repository owner, @viceice, should have access to this functionality.

It sounds as if we should add a brief section to About task lists that includes a screenshot with the "Convert to issue" icon displayed.