We have not yet removed the help files. We can use this commit as a
conversion commit since a lot more help changes will be merged before
this PR gets merged. We will need to rebase on top of main, run
conversion step in this commit, push those changes and then merge the
PR.
NOTE: This commit temporarily breaks the astro build since we have
renamed the path in the MDX files from starlight_help/ to help/ early.
That should be fine since astro build will not break any tests right
now.
We should squash this commit with the next commit removing help center
files when merging into main and remove this NOTE.
We are starting the cutover process and starlight_help is the directory
we have agreed on to place our new help center project. We do not want
to use `starlight_help` as the URL for the project, but this commit
changes the url from `help-beta` to `starlight_help` temporarily since
we can only change URL once we get rid of the current help center
project. That will be done in a future commit.
We chose not to edit the original markdown files to make this change
since the conversion script logic can be used for removing these lines
with very little changes and we don't need the original markdown source
files to be edited before the cutover.
The css for making loose and ordered lists look same has been removed
since we wanted to to respect commonmark specification.
We remove the ol > li margin rule to space out ordered list items since
that was the result of us overriding an upstream margin rule in
steps.css.
We inserted Steps inside include files only if they are not entirely
composed of an ordered list. If they are, they will eventually be
wrapped inside FlattenedSteps and wrapping these macros with Steps will
not give us the results we desire.
Using steps.css right now might feel like the more convenient way out,
but it might introduce friction in upgrades when the upstream code
changes. To tackle that, we convert FlattenList to FlattenedSteps and
explicitly use the steps component.
Use the icon's name, in camelcase, with the suffix "Icon" for
icon class names in the new help center documentation. E.g.,
zulip-icon-external-link becomes ExternalLinkIcon and fa fa-plus
becomes PlusIcon.
A lot of our admonition declaration had an empty new line in the
beginning which was getting ported over in the conversion. This caused
the asides to unintentionally mark a tight list as loose which we do not
want.
FlattenList was not able to handle other components inside a list in the
past, but that has changed in the past few commits and we no longer need
to check for tips in include files for `is_include_only_ordered_list`.
We had some include files that started with another include, and in some
cases this nested included file was also `only` an ordered list. In that
case, we need to add a flattenlist around the file, but our current
conversion script was not accounting for that.
We do not want to have a heading for every tip and thus we created a
custom component for our aside. We want to add a lightbulb icon and the
text `Tip:` is bold as a prefix for every tip as if it was already part
of the text. To do that, we cannot insert both of those as html seperate
from the slot html, we had to access the slot html and insert both of
them into the HTML tree.
The regex we were using for file includes was searching for the syntax
at the start of a line but the file includes can be followed by a `- `
as part of a list item, due to which 15 occurences of includes were not
being converted. This commit fixes that.
Fixes#31253.
We've added another env variable called `SHOW_BILLING_HELP_LINKS`.
This env variable is set to `settings.CORPORATE_ENABLED` if the
`build-help-center` tool is used.
When we were doing it later, the issue we encountered was that when we
add support for relative links in the future, relative path fixing was
happening after `relative/help` had been added to the modified markdown
file, replacing it with `relative/help-beta` which wasn't the
replacement we intended.
Fixes#31254.
We are using `SHOW_RELATIVE_LINKS` as the env variable to set if we
want to show relative settings link or non-linked markdown instructions.
We are not trying to determine `SHOW_SETTINGS_LINK` by ourselves. See
https://chat.zulip.org/#narrow/channel/49-development-help/topic/Passing.20sitename.20for.20astro.20project.20in.20production.2E
for more details.
Until the cutover happens, we would need to manually update the mapping
in both the astro component and the python file, but since that mapping
is not frequently changed, that is a tradeoff we can make.
We had to add margin-bottom: 0 to icon styling since starlight was
inserting a margin-bottom of 1.25 em for list items.
We want to follow the Astro way of doing things and the middleware was
adding more magic + it was violating commonmark spec:
https://spec.commonmark.org/0.31.2/#example-301.
We insert FlattenList component where include files are being
treated as part of ordered lists. Astro renders included files as it's
own component, which would result in multiple ordered lists instead of
a single list if we did not use this component. See the astro component
file itself to know more how FlattenedSteps works.
We are not inserting FlattenList component for files with !!! tip
components, since we need to do it inside the include file. There are 4
such files at the time of writing this comment.
`is_include_only_ordered_list` makes sure of that. We can do the
conversion for it manually during cutover or in a followup PR.
All unordered lists at the time of writing this comment are standalone
components and we do not need to do any transformation for them.
We also changed the order of conversion of include and main files.
Include files are now being converted first to calculate
include_files_info.
Relevant topic:
https://chat.zulip.org/#narrow/channel/19-documentation/topic/Stage.202.3A.20New.20syntax.20for.20imports
Fixes#31248.
For cases with zero tabs in our current help center, we were using the
tab syntax just to put a border around the instructions without any tab
label. We do not want that border anymore since Tabs also don't have any
borders. So, we just remove the old tab syntax in that case during our
conversion.
We also move the admonition to asides conversion before the tabs syntax
conversion since the tabs conversion happening first was messing with
the asides conversion and was resulting into some missing closing tags.
We can modify things to work regardless of order, but doesn't seem worth
digging into for a conversion script.
Fixes#31249.
We have converted `warn` to `note` since that was the translation that
remains most faithful to how we display `warn` admonitions in our
current help center implementation. See
https://chat.zulip.org/#narrow/channel/19-documentation/topic/Stage.202.3A.20New.20syntax.20for.20!!!tip.20in.20help-beta/near/2174415
for more details.
We've also duplicated code from Python-Markdown to represent how
admonitions worked there more accurately. Duplication should be fine
since this is a one-off script and Python-Markdown is not a project
that's gonna change drastically in the future.
Earlier, we were just renaming the files in help/include and copying
them over. Which meant that none of the mdx features or any of the
components we add could be used there. We could also not support nested
imports which are a part of the help/include files.
We also set an explcit height and width of 1em for icons, since some odd
behaviour for icon height and width was noticed when writing this
commit. unplugin-icons sets height and width by itself. It was setting
the height to 1024 and 960 for some icons. It is better to set the
height explicitly.
The previous logic could not handle adding the given string at the 1st
line. We also rename the function to accurately represent what it does,
insert_string_at_line.
In future, we intend to add a function that will read the include files
and do a conversion to mdx. That conversion will be different from the
conversion that we are doing right now for the main help files. That is
why we have extracted the markdown file reading logic to the
`get_markdown_string_from_file` and renamed `convert_string_to_mdx` to
`convert_help_center_file_to_mdx` to be more specific for help center
files.
In `replace_icons`, when replacing zulip icons, the original
`markdown_string` was being passed instead of the result from the
previous font-awesome icon replacement.
In our app, we use the font-awesome stylesheet, add it to our webpack
bundle and use the appropriate class with the <i> tag.
Here. although for font-awesome, we can use the stylesheet to do the
same, we would need to use `webfonts-loader` for our custom icons.
In this astro project, we want to follow the Astro way, and
unplugin-icons fits better with the Astro way of doing things.
See this topic on the discussion on how we chose unplugin-icons:
https://chat.zulip.org/#narrow/channel/19-documentation/topic/Stage.202.3A.20Icons/near/2168842
Before this, every function itself was responsible for adding it's own
imports. That is extra string manipulation which we had to think about
everytime we were adding new conversion function.
Now, we have an import statement set that the functions can modify, and
we have a function responsible for adding those imports. This makes it
easier in the future to add more conversion functions which might be
introducing imports.
Fixes#31252.
One of our major use cases for file imports is to have bullet points as
partials to import at different places in the project. But when
importing the file with Astro, it creates its own lists. So we merge
lists together if they have nothing but whitespace between them.
There were some talks to use a component called FlattenList that would
flatten the list inside it, but that would also flatten lists that were
nested on purpose. This approach while feeling a bit hacky would not
flatten nested lists.
We use all these markdown files in `include` only to import them into
our main help markdown files. Most of these files are bulleted lists of
text. When importing these files, they might appear as an indented
sublist of an existing list. We plan to introduce mechanism to flatten
it in further commits.
This is the tool that we will consistently use for our project to
migrate our help center to use starlight.
We're only doing string manipulation in this tool for now, we will
start to use existing markdown preprocessors whenever appropriate
as we start to add support for different components.
Running the tool again will overwrite the existing files.
