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.
