The indentation in the original files was fine for the current help
center, but when converting the files to MDX, the indentation made the
includes and the code blocks look like they were on the same level as
the list item and not part of it.
I did a manual check of code blocks with indentation in help/ and how
they looked when converted to the new help center and the rest of the
cases looked fine.
For included files, our conversion tool needs a file just to be an
ordered list to properly surround it with FlattenList. If there is
heading and description in the file, the conversion script will not
insert FlattenList. So, we just create two different include files in
this case, first for the heading/description and second for the ordered
list.
In our current implementation, loose lists and tight lists look the same
visually. Loose lists are lists with blank lines between list items, and
the contents of a list item should be enclosed in a paragraph tag in
that case. For unordered lists, paragraph tags have a bottom margin in
starlight and thus looses lists look much more spaced out than tight
lists.
That is not the behaviour we had in mind while writing the
documentation, the reason we had all these loose lists is to make the
documentation easy to write and read. So we attempt to remove all the
blank lines and fix the problem at source. Since paragraph tags are used
for other purposes in a list in starlight, it won't be a wise decision
to let the source be as is and just change things in css, other expected
behaviours might break in that case. See this topic for more details:
https://chat.zulip.org/#narrow/channel/19-documentation/topic/new.20help.20center.3A.20regressions/near/2226084
All the changes were made by a one-off script which has not been
commited to the repo. The script wasn't perfect and could not decide
between blank lines that make a list loose vs blank lines necessary for
a sub-list or a code block inside a list item. A manual review of all
the changes was done before making this commit to ensure that no
unintended changes were made to the help center files.
This updates the topic name format for Slack threads to include a
snippet of the original message. Currently the format looks like this;
"{date} Slack thread {n}", which provides little to no context about the
thread.
Currently we also use the `thread_ts_str` key to keep track of Slack
threads we're converting, this key format makes it so that it has a
small chance of combining threads with the same timestamp under one
topic. This commit updates it to use a new key format, `thread_key`.
Fixes#27661.
The conversion script for help-beta assumes that all items in a numbered
list start with 1. which was a wrong assumption. This commit attempts to
fix that. We are not introducing any lint step to tackle this since it
will be easy to just check for this again before the cutover happens.
We do not change this for `numbered-list-examples.md` since that example
shows how the current numbered lists work and we might still want to
show that. We can decide what to do with that file once the time of
cutover arrives.
Renames file and redirects existing links to "help/user-roles" as
the previous content tracks to that current file's content.
Updates existing links (excluding ReadtheDocs) to go to either
"help/user-roles" or "help/manage-permissions" depending on which
help center article applies to the content.
In the help center and production documentation, replace links to
the "Getting your organization started with Zulip" guide to the
new "Moving to Zulip" guide.
Previously, the help center has a broken link that just points to
Slack's help center. With this change, we will remove and replace the
link to their OAuth scope section.
These files are not Jinja2 templates, so there's no reason that they needed
to be inside `templates/zerver`. Moving them to the top level reflects their
importance and also makes it feel nicer to work on editing the help center content,
without it being unnecessary buried deep in the codebase.
