Linking tutorial steps with q2 plugins

Dear qiime2 team,
First, congratulations on the excellent work you have done and the tidy organization of the website. I have a suggestion that might be helpful to users, especially beginners. I think it would be nice to have plugins links available in each tutorial step. something similar to qiime1 tutorials. This will give the chance to readers to click (open a new page) and learn more about the plugin and the other available options. I will be even better to have it both way i.e. adding tutorial links at the plugin pages but this might be asking too much :smile:

Thank you all and keep the great work,


1 Like

Thanks @Ahmed_Abdelfattah! This is a great idea, and would love some help implementing - just let us know if you want to join us! :qiime2:

1 Like

@thermokarst I would like to help, just let me know how you would like to proceed

1 Like

Well, maybe the next step is to brainstorm some ideas. Perhaps the link is embedded in the command:

Or, maybe there is a list of links before or after the command block:

Or, maybe some other option altogether? What do you think, @Ahmed_Abdelfattah? Also curious to get @ebolyen's thoughts here, too.

Thanks! :t_rex: :qiime2:


@thermokarst I think the first option is more elegant and easier. they basically hyperlinks to other pages, right?
As second step, a wiki style would be also nice i.e. whenever plugin name appears in text. like this

Thanks for asking for my opinion :smiley:
Let me know :speaking_head:

1 Like

The inline links look great - I love that idea!

Would you be interested in contributing to the docs, adding in those inline links? Some from the community would be able to lend a hand with that, if you desired.

Yep, they would link back to the documentation for that particular plugin and/or action.

I think adding the links in the command blocks will probably be a slightly longer process compared to your proposal (those command blocks are built using some custom code in our documentation process, so it will require a little massaging). You are welcome to lend a hand there, too, but I suspect the inline links will be a better payoff in terms of initial time.

Let us know! And thanks again for the recommendation - QIIME 2 is a team effort! :qiime2:


I would be happy to add these links. Just let me know how and when to start!

Not a problem, let’s then start with the inline links and see how it goes.

Glad to be able to help and looking forward to making tangible contributions



:tada: :champagne: :qiime2:

Cool! Well, I think the next step is to get you set up with the docs code repository, make sure you have a git client installed on your workstation, then getting the doc dependencies installed on that machine!

  1. Docs Repo:
  2. Git client: if you have used git before, I will leave this setup to you. If you are new to git, maybe it is worth checking out GitHub’s client. This will let you download the code for the docs somewhere locally on your computer.
  3. After you have the source code on your computer, activate a qiime2 environment. For this, it might be beneficial to install a new qiime2 environment (you can have many side-by-side).
  4. Navigate to your newly downloaded docs repo in a terminal, and run the command pip install -r requirements.txt - this should install the doc dependencies in your env.
  5. Run make preview to generate a simple test build. When that finishes another command will display that will instruct you on how to launch a local web server to view the changes in.
  6. If you have made it this far, time to think about making a git branch and starting to make changes to the docs!

Okay, that is a really high-level overview, so don’t worry if something is confusing or left out - just let us know if you need a nudge in the right direction! If this is all new to you, I know this might seem like a lot, but we are all here to assist. Once you get all geared up, we can get going on the actual code changes!

Thank you!! :qiime2:


Thank you @thermokarst for the detailed steps.
I made it fine until step no. 5 i.e. run make preview, I got the error that you can see in the attached file.
sphinx-err-q6xa1466.txt (1.5 KB)
I tried to install a new qiime env. as you suggested but the problem remained.
Do you know how can I solve this issue?

Hey there @Ahmed_Abdelfattah!


It looks like the directory you are working in doesn’t have write permission for your user. You will either need to modify the ownership of the directory, or, you could do this in a directory that you already have permission to write it. Let us know if you get stuck! :qiime2:

1 Like