Adding a page Alert - errors and inconsistencies

[JoelMTaylor]

Hello again,

Thank you for your help with the Azure page setup. We are still trying to tweak the Azure side, but your assistance was most helpful in getting it to a functional state.

For the documentation website, we are going to have one of two alerts at the top of the page to inform the reader about whether the page and content has been reviewed:

!!!success
This article has been formally reviewed and approved for use.
!!!

or

!!!warning
This article has been published for your convenience. It has not yet been formally reviewed for policy compliance.
!!!

I have been testing the placement of the Alert, Main Heading and Metadate content (author, categories and date, mainly). During the testing, a few situations came about:

1. Author, categories and date being spread across the screen.
2. Text not displaying
3. Alerts not displaying

After further investigation, it seems that the build and deploy of the content from Retype is not working properly (somehow becoming corrupt in the process). In some instances, a build/deploy will fix or break the content displayed (even though the page does not change). I did think that it could be related to the Azure side of things, but realised that the built *.html pages are corrupted (and Azure only displays it).

I have copied some screenshots and *.html files to show as examples. They can be viewed at https://joelmtaylor.github.io/Documentation/_example files/....

Geoff (or Fabricio), if you want, we can give you permissions to view the repo https://github.com/ccmltd/docs-corportatesystems.

[geoffreymcgill]

Geoff (or Fabricio), if you want, we can give you permissions to view the repo https://github.com/ccmltd/docs-corportatesystems.

Please. Access to the repo should help.

[geoffreymcgill]

It looks like the number of categories is not wrapping. You are assigning a lot of categories to the document, which creates a long list.

To test, can you try commenting out about half of those categories?

categories:
  - Edumate Coordinators
  - Teaching Staff
  - Registrar
  - Office Administrators
  - Student Services
  - Fees & Finance
  # - Timetablers
  # - Curriculum Leaders
  # - Student Welfare
  # - Aides & Support
  # - Staff Management

I guess we just never assumed that many Categories would be used.

This is a bug, but should be an easy fix.

I'll look through the site and see if I can notice any other issues.

[geoffreymcgill]

That <br> at the top of the page should not be required and can be removed.

https://github.com/JoelMTaylor/Documentation/blob/main/CorporateSystems/Multi-factor%20Authentication.md?plain=1#L29

[JoelMTaylor]

I tried the test to see if commenting out categories did anything. I didn't have any success. The examples files are:

• https://github.com/JoelMTaylor/Documentation/blob/main/_example%20files/comment%20out%20categories%20-%20MFA.html
• https://github.com/JoelMTaylor/Documentation/blob/main/_example%20files/comment%20out%20categories%20-%20MFA.png

I removed the <br> to no effect. I tried many variations. For some reason, I didn't think to try that (maybe because it had an error the first time).

[geoffreymcgill]

All the <br> tags can be removed. Removing may not fix the rendering of the page, but nevertheless they should be removed.

There does appear to be a problem with how Retype is handling the date parsing. In your CorporateSystems/Multi-factor Authentication.md document, you have an invalid date set to date: 2021-03-1902. This appears to be causing Retype to fail in a strange way and that might be causing the rendering the issue.

https://github.com/JoelMTaylor/Documentation/blob/main/CorporateSystems/Multi-factor%20Authentication.md?plain=1#L7

Can you try setting to date: 2021-03-19?

[geoffreymcgill]

@JoelMTaylor The defect where configuring many categories caused a formatting issue has been fixed in the v2.3.0 release which is now available.

Hope this helps.

[geoffreymcgill]

If you have a frontmatter block, it will need to be the first thing on the .md page.

The following page will render, but not as you expect it to render as the frontmatter block is not the first item on the page.

https://github.com/JoelMTaylor/Documentation/blob/main/admin/Test%20Order%20Start3.md?plain=1#L2-L4

Also, those <br> tags should be removed.

Hope this helps.

[geoffreymcgill]

A nice optimization that might work well for your project is moving each of the author configs into an include file.

For example, if you create a _includes/sara-dawson.md file:

_includes/sara-dawson.md

authors:
  - name: Sarah Dawson
    email:
    link:
    avatar: ../static/SarahDawson_Icon.png

and then just include that sara-dawson.md file into each page using {{ include "sara-dawson" }}, see:

sample.md

---
{{ include "sara-dawson" }}
categories:
  - Edumate Coordinators
---
!!!warning
Sample warning
!!!

# Heading Here

Text

This would allow you to manage just one instance of the author details for each author, and just include that chunk of configuration across many pages. Instead of reproducing and maintaining the exact same content on many individual pages.

Hope this helps.

[geoffreymcgill]

Can you change the following line to use the @latest tag, instead of @v2?

https://github.com/JoelMTaylor/Documentation/blob/main/.github/workflows/retype-action.yml#L17

# Old
# - uses: retypeapp/action-build@v2

# New
- uses: retypeapp/action-build@latest

[JoelMTaylor]

@geoffreymcgill, you have been invited to the repository and you can access the repository website (which can be found in the reytpe.yml).

Hopefully, this will be more useful in tracking down the issue. However, if the answer cannot be found, I have been considering restarting from scratch.

[geoffreymcgill]

Thank you. I was able to immediately reproduce the issue. There's something very strange going on with how the frontmatter block is being parsed and rendered. I'm working through a few tests to try and create a simplified sample that demonstrates how to reproduce the issue in an empty test project.

I will keep you updated with my progress.

[geoffreymcgill]

We were able to isolate the issue to malformed icon configurations.

When using emoji shortcodes, the shortcode must be wrapped in double-quotes ". For instance, using icon: ":telephone_receiver:" instead of icon: :telephone_receiver:

# Existing
icon: :telephone_receiver:

# Revised
icon: ":telephone_receiver:"

I sent a pull-request with changes to three files with this icon formatting issue.

You will need to restart your instance of retype watch. First run ctrl + c to exit out of retype watch mode, then run the command retype watch again to restart the server. That should clear out the old bad formatting and things should be working better now.

Fixing those three icon configs does seem to fix the issue, but Retype should have handled those errors better. We are going to investigate and try to figure a better way to recover from those formatting errors.

I will keep this thread updated with our progress. At least for now, this work-around should at least fix the massive formatting issue.

[JoelMTaylor]

@geoffreymcgill, thank you for your assistance - we certainly wouldn't have been able to fix it without you.

[geoffreymcgill]

We were able to isolate the fix the defect that was causing the under lying formatting problems when the emoji shortcodes were unquoted. It was a very interesting problem, thanks for reporting.

The fix will be available in the upcoming Retype v2.3.0 release.

There's nothing different you will need to do in your app, but still continue to wrap emoji shortcodes in double-quotes, such as ":shortcode-here:".

Hope this helps.