Documentation Plugin - Index Topic not working after Restore

[alltiagocom (Tiago)]

A few months ago I installed Discourse, added some topics as Index Topic in the Documentation Mode section. Everything worked as expected.
backed up everything, deleted the Digital Ocean account, etc.

A few days ago I installed Discourse again and restored everything from the backup file I created and everything is working, except for the Documentation sections. At first I thought maybe the issue was that I unlisted those index topics, but they were unlisted before I uninstalled everything and they were working, so that couldn’t be the issue. Still, I tried to list them, but no luck. The sidebar was still showing the categories and all that other stuff that is the default.

Then I decided to copy the original topic’s content and create a new topic with it, set it to Index Topic, and that one works. Also closed and unlisted like the one that’s not working, so closing and unlisting is not the issue.

It seems that in the restore process, something is breaking the documentation mode for some reason.

[nat (Natalie T)]

Just checking - have you seen this?

@nat

Updates for self-hosters

For self-hosters using this plugin, our most recent update would require a manual rebuild of the index. This would involve running this rake task:

bundle exec rake doc_categories:build_sidebar

# if running the task above fails due to NoDatabaseError,
# run with the following for typical self-hosted setups
sudo -E -u discourse bundle exec rake doc_categories:build_sidebar

If you are not able to run this rake task, you may go to each documentation category’s settings, remove the category index, save, add it back, and save. This would rebuild them and refresh the category cache as well

[alltiagocom (Tiago)]

Thank you for the link.
Since I’m still building the whole structure, I ended up just creating a new topic, copying and pasting the content from the old one, and delete the old topic. I only had 2 of those anyway.

So, my question is: is that rake task something I need to do every time I update Discourse? Or just when I restore (if I do it again in the future)?

[nat (Natalie T)]

No, that rake task is just a one-time thing from the date of that quoted post.

You shouldn’t need to re-create the topic though, just going to category settings, unlinking, saving, and relinking the existing topic at least should work.

[RGJ (Richard - Communiteq)]

@nat

that rake task is just a one-time thing from the date of that quoted post

Just wondering - why wasn’t this implemented as a migration?

[nat (Natalie T)]

From what I recalled at that time — It couldn’t be a migration. Migrations ideally don’t touch application code (because code can drift from when the migration is intended and error out).

The PR also indicates the reason:

This PR also includes a rake task (doc_categories.rake ) for rebuilding sidebar sections and links from active doc index topics – this is not exactly recommended to do in a migration as it would involve either using the parser or nokogiri (which implementations can drift and cause an invalid migration).

[alltiagocom (Tiago)]

So, if I understand it correctly, from now on, I don’t need to do any of that? The rake task or the relinking process, whenever I update Discourse?

Just want to make sure I understand it.

[nat (Natalie T)]

Yup. It was only a one-time thing.

[alltiagocom (Tiago)]

Awesome! Thank you for clarifying!