Dedicated Documentation Section

[Ayu]

I want to implement fontsource/fontsource#79 soon as I think this project has matured enough and it's a good opportunity to actually reduce the size of our README.md. I want to move most of our documentation over to the site, which can then allow me to add a lot more in-depth explanations and examples (because I previously felt the README would become too long if I added a lot more).

I'm thinking of just Markdown docs that could add new pages to the documentation with a file structure such as:

-Installation
----Webpack
----Sass
-Variable Fonts

This way, we could add more pages if need be as we add more features and different methods of installation. It also allows us to be more organised with how we document differing parts of the project.

Then you would not need to process the README's of each font and instead, just let it act as a preview function with all the included supported variables? Maybe it'd also have a bit like yarn add @fontsource/<fontname>. I'll be removing a lot of the information on the package README's in favour of the docs hosted onsite.

What're your thoughts on this?

[John Wesley]

That sounds good to me. I was thinking maybe we could use markdown to create the individual pages, and then use the Lodash's template function to replace variables with their corresponding values. Then we can use react-markdown to convert the markdown files to react. Obviously, this is just one way of doing it, if you think of a better way, I am all for it.

[Ayu]

That sounds good, I'm all open for that. Let me know if you have any questions!

[Ayu]

Also, perhaps a nice addition would be add subsections in the sidebar nav for every heading in the markdown document.

e.g
-Installation
--Sass
---fontFace
---fontFaceCustom

The two at the end are just subsections in the same document, differentiated using header markdown.

It's not necessary, but just an idea for ease of access. It doesn't even need to automatically detect such things, because when updating documentation, it shouldn't be an issue to manually update the sidebar nav to link up with the headings. That way, even I can just use a component to update things without pinging you.

Thanks for your willingness to help out though. I really do appreciate your work here.

[John Wesley]

I have uploaded a draft of the new search directory to the dedicated-markdown-documentation branch. Currently, all the pages are stored in the pages directory in markdown format. The index.js file is where you import each markdown file. The files are exported as an array from the index,js file. You can add another page using the following syntax:

{
  label: /* the value to be shown in the navigation */,
  id: /* a unique value used to identify the page(unneeded if their is no corresponding page) */,
  icon: /* a react svg icon displayed next to navigation label(optional) */,
  children: [] /* an array of nested navigation items(items use the same format as being explained now) */,
  page: /* a markdown file imported with javascript */
}

The font template is used to display information for each font. All variables from a fonts corresponding metadata.json file can be used in the template.

    ```special
    FontViewer
    ```

    The above code tells the markdown parser to insert the font viewer in that specific location.

Changes to the index.js file in the pages directory should automatically reflect to the site. If their is any confusion please look at the files themselves or let me know if there are any questions.

[Ayu]

Small things to poke at, but it looks great!

• The Fonts tab probably should be open on load instead of closed.
• For the docs, there seems to be unnecessary margin to the right which makes presentation a little awkward.
• I feel we need to update the typography styles for the headers to be a little bolder, maybe? Also, just like Markdown, the largest header should also have a light divider underneath which should help the docs be a bit more readable.

Everything else seems fairly easy to pick up. Thank you.

[Ayu]

Actually, it seems like the typography styles seem to have largely changed from the live project and the branch itself. The live build doesn't seem as off, whilst the branch looks really different.

This:

Vs:

[John Wesley]

I have fixed the problems you listed in commit 8a024f8.

[Ayu]

Looks great! I'll need some time to rewrite the documentation (very busy this and next week) and I'll commit to this branch. Once ready, I'll ask for your confirmation and input to merge it into production.

One bug to report is that search is pretty much broken with the new format. That's something to look into.