Enquiry and Suggestions: Authors, Emails, Columns, Octicon Icons, Headings, Titles and Captions

[JoelMTaylor]

Hello,

I have been transferring documentation from SharePoint to Retype. In the process, I have encountered some issues that I could not find solutions for. If there are no solutions, then these would be suggestions for future updates.

My site is https://joelmtaylor.github.io/Documentation/. I will provide further directions to specific examples.

Author, Emails and Columns, and Octicon Icons
Page: https://joelmtaylor.github.io/Documentation/edumate/edumate_main-support/
In the Columns, there are two 'issues'.

1. I have an Author on every page. I would like to include the Author's job title. I could not find anything in https://retype.com/configuration/page/ that would allow this. I am trying to achieve something like:
   
2. The emails are automatically generated into Mailto. This isn't necessarily a poor or incorrect setup, except that I have an example email that would not work ("edumate-support@yourschooldomain"). Therefore, I would want this to be generated as a Mailto. I tried escape characters, but they did not work.
3. As you can see in the first column (second row), the email overflows the column. This seems to be happening because it can't split text. I would describe this as an issue - although very, very minor. (I suppose it would depend on the screen, but in my 24" 1080p monitor, it overflows very slightly.)
   
4. Down the bottom of the page, I tried to create a button with an icon inside. However, I could not get the icon="code-of-conduct" (https://octicons-primer.vercel.app/octicons/code-of-conduct-16) to work. I tried many variations - just to be sure. I suppose it has to do with code-of-conduct.

Headings not included in sidebar contents
Page: https://joelmtaylor.github.io/Documentation/learnerlink/teams-student-classes/ [Note that the specific page mentioned above is not required, but just an example.]
I greatly appreciate the inclusion of the sidebar contents navigation (the one of the right). It is helpful and adds to the presentation of the page. However, there are some situations where I would like the appearance of the heading in the page content, but without including that heading in the contents.

I attempted the solution here: https://bookdown.org/yihui/rmarkdown-cookbook/toc-unlisted.html, but I was not surprised to find that it doesn't work. I found that H4 and H5 are not automatically included in the contents bar. Thus, I have just been using these in the place of H2 and H3 where required.

Page Title and captions
Page: https://joelmtaylor.github.io/Documentation/edumate/attendance-workflow/
I have been using the options to manage the page metadata - specifically to have a different title in the sidebar navigation (left side) to the H1. For some reason, this page does not display the title from the page metadata. I have tried different titles and deleting it, but to no effect.

Also on this page, I used a table to separate images side-by-side. I included captions, but they do not appear in the table. Captions appear to be working normally throughout the rest of the pages. This is also a minor issue, I just wanted to mention it.

Summary
Most of these 'issues' are minor and I am not overly concerned if there is no solution. If there is a solution, I would be pleased to know (so I can implement them). Otherwise, I have found some workarounds or it just isn't important.

I apologise if it is most unusual to post all the issues in the one discussion. However, some of them were related and I could not justify making multiple discussions for minor questions or comments.

[fabriciomurta]

Hello, Joel, I will try to help you with a few of the points you raised.

I have sent a pull requests to your repo suggesting a change to switch Retype to version 2 (JoelMTaylor/Documentation#1). It is still using version 1 and, as a major version update, it would require the workflow file to be changed manually. This shouldn't be necessary again until we release a next major version (v3), which we don't plan to in the short term.

---

I have an Author on every page. I would like to include the Author's job title.

There's no specific means to do so, yes. If you're okay with how it looks, you can just change the author line into: Author Name<br /><small>Author's Title</small>.

The issue though is that the title becomes a little too far from the author name, and the name+title, while centered with the portrait, will no longer be aligned with the by text before the portrait.

---

I have an example email that would not work ("edumate-support@yourschooldomain"). Therefore, I would want this to be generated as a Mailto

I take it you don't want that email to be wrapped in mailto:// link, right? If so, just escape the at symbol (@), so edumate-support\@yourschooldomain)

I sent this change as pull request (JoelMTaylor/Documentation#3) to your repo.

---

As you can see in the first column (second row), the email overflows the column. This seems to be happening because it can't split text. I would describe this as an issue

Yes it really doesn't look right to just overflow to the neighboring column or outside the page. But it might become tricky to decide when exactly to wrap an e-mail as it may hurt considerably the page's readability.

It looks like the panel approach you took below might be a much better approach! But of course you already saw that coming, right?

A quick way to overcome that would be to turn the automatic links into manual links and do the split yourself, something like:
edumate-support@ccmschools.edu.au => [edumate-support@ ccmschools.edu.au](mailto://edumate-support@ccmschools.edu.au)

We have created an internal issue to improve this scenario.

---

I could not get the icon="code-of-conduct" (https://octicons-primer.vercel.app/octicons/code-of-conduct-16) to work.

The icon was introduced in Octicons 16.2.0. Retype 1.11.2 used Octicons 16.1.1. Once you accepted JoelMTaylor/Documentation#1 the page should render the icon for the right syntax you used across all your attempts, which boiled down to:

[!button variant="primary" corners="square" target="blank" icon="code-of-conduct" iconAlign="left" text="Edumate Support Portal"](https://support.edumate.app/)

---

there are some situations where I would like the appearance of the heading in the page content, but without including that heading in the contents.

Hmm I don't think we have this feature at the moment... We shall log this as a feature request, maybe? You can probably hack your way thru visuals though, now that you can use custom properties in headings, to make your H4, etc, look "bigger", but that's far from optimal. That reference you posted to toc-unlisted markup should help us deciding how to enable this feature.

---

For some reason, this page does not display the title from the page metadata.

Yes, it won't process YAML code if it is not in the format the specification supports. I have provided pull request #2 (JoelMTaylor/Documentation#2) suggesting the fix. That was just a matter of properly indenting the Front Matter code. That's a whole strict YAML specifications, we can't really loosen its rules as it would break other scenarios that it probably already thought of.

---

I used a table to separate images side-by-side. I included captions, but they do not appear

You got us on that one! Captions are being suppressed if an image is wrapped within a table cell. We have created another internal issue to track this one.

---

Thanks, your feedback is awesome! We are happy that you're finding your way through with Retype as your documentation tool!

We shall post an update here when related issues are fixed in Retype, but at least a reference to this discussion will be in our changelog once they are included in a future release, so stay tuned!

[JoelMTaylor]

Thank you @fabriciomurta for the detailed response and the assistance with the pull requests.

I was particular stumped on the meta data issue. I should have thought about checking the YAML code.

Thank you all for the work that is being done. Retype is a very good tool and all the effort that is put into the documentation is very helpful to understand and follow.