Test of Markdown converter

[ExperimentsInHonesty]

Overview

We need to evaluate the google docs to markdown converter to determine if its going to work so that we can use it for transitioning our WIP guides

Action Items

• Add link to converter tool into the resources section
• Test out functionality
• define what is missing or problems we will have solve

Resources/Instructions

Google Docs to Markdown Converter Tool
Jump to Comment - Markdown Converter Documentation
Docs to Markdown Wiki

[ExperimentsInHonesty]

>>>>> gd2md-html alert: ERRORs: 0; WARNINGs: 0; ALERTS: 16.

• See top comment block for details on ERRORs and WARNINGs.
• In the converted Markdown or HTML, search for inline alerts that start with >>>>> gd2md-html alert: for specific instances that need correction.

Links to alert messages:

alert1 alert2 alert3 alert4 alert5 alert6 alert7 alert8 alert9 alert10 alert11 alert12 alert13 alert14 alert15 alert16

>>>>> PLEASE check and correct alert issues and delete this message and the inline alerts.

---

GUIDE:

WRITE A ONE SHEET

AN EASY HOW-TO

**What **is a One Sheet

A One Sheet is a one page overview of a Hack for LA project. It includes a brief overview, what has changed in the last 6 months and what is on the roadmap for the next 6 months. These are used to create alignment between project team/stakeholders and Hack for LA org as well as sharing updates with stakeholders and funders.

**Create **an issue for the One Sheet

Review Product Management Issue hackforla/UI-UX#3 and One Sheet Tracker to determine if a One Sheet already exists for the project and choose the appropriate issue template below:

• Updating a One Sheet
• Start am issue for making a new One Sheet

Update the Issue to apply all the correct information:

1. Click on the Gear Icon next to **Assignees **to assign the issue to yourself. If you are unable to assign yourself, you may not have the right access. Refer to this issue to resolve this.

>>>>> gd2md-html alert: inline image link here (to images/image1.png). Store image on your image server and adjust path/filename/extension if necessary.
(Back to top)(Next alert)
>>>>>

2. Confirm that the labels documentation and** feature: one sheet **are applied. Click the gear icon next to **Labels **to add these if they are missing.

>>>>> gd2md-html alert: inline image link here (to images/image2.png). Store image on your image server and adjust path/filename/extension if necessary.
(Back to top)(Next alert)
>>>>>

3. Click on the Gear Icon next to **Projects **to add the issue to the Project Updates for Website and Org project

>>>>> gd2md-html alert: inline image link here (to images/image3.png). Store image on your image server and adjust path/filename/extension if necessary.
(Back to top)(Next alert)
>>>>>

4. Save the issue then move the issue from the Ice Box to In Progress (actively working)

>>>>> gd2md-html alert: inline image link here (to images/image4.png). Store image on your image server and adjust path/filename/extension if necessary.
(Back to top)(Next alert)
>>>>>

**Update **an existing One Sheet

Do not make any edits to existing One Sheets, the file is live and could be in use by someone else.

Create a copy of the One Sheet

1. Open the existing One Sheet and click on File -> Make a copy.
2. Give the file a name that reflects the Quarter/Year it’s being updated for
3. Save the copy in the Product-Management \ Product One Sheet Drafts folder

>>>>> gd2md-html alert: inline image link here (to images/image5.png). Store image on your image server and adjust path/filename/extension if necessary.
(Back to top)(Next alert)
>>>>>

**Create **a new One Sheet

Create a new one sheet using the template.

• Start by creating a copy of the existing One Sheet.

>>>>> gd2md-html alert: inline image link here (to images/image6.png). Store image on your image server and adjust path/filename/extension if necessary.
(Back to top)(Next alert)
>>>>>

• Save the copy in the Product-Management \ Product One Sheet Drafts folder

>>>>> gd2md-html alert: inline image link here (to images/image7.png). Store image on your image server and adjust path/filename/extension if necessary.
(Back to top)(Next alert)
>>>>>

Find information to update the issue

Start by getting to know the project and what it’s about. Resources to review:

• Review the existing One Sheet if it exists
• HackForLA project page
  • If you are working on a project for an organization other than Hack for LA, the location may differ
• Join the project slack channel
  • The slack channel is listed on the HackForLA project page
• Meet with the current Product Manager(s)
• Github project page
  • The Github project is listed on the HackForLA project page
  • Click on Projects from the Github page to access the project board to identify the active project board

>>>>> gd2md-html alert: inline image link here (to images/image8.png). Store image on your image server and adjust path/filename/extension if necessary.
(Back to top)(Next alert)
>>>>>

* Look through items in the “Done” column to start understanding the work that has been done

• The project’s google drive may have additional information
  • It’s up to the project team to determine if this access is needed
• Look at other projects One Sheets for context and inspiration
  • This issue contains past examples to review
  • The Project Management Google Drive One Sheets Folder may contain other examples

**Update **the One Sheet Issue

The issue needs to be updated so that progress can be tracked by anyone who looks at it. Links to the existing and new documents need to be added for easy review.  

• Click edit on the issue

>>>>> gd2md-html alert: inline image link here (to images/image9.png). Store image on your image server and adjust path/filename/extension if necessary.
(Back to top)(Next alert)
>>>>>

• The links should be added to the Resources/Instructions section .

>>>>> gd2md-html alert: inline image link here (to images/image10.png). Store image on your image server and adjust path/filename/extension if necessary.
(Back to top)(Next alert)
>>>>>

• Use the link function to create the hyperlink, which will automatically enter the format

>>>>> gd2md-html alert: inline image link here (to images/image11.png). Store image on your image server and adjust path/filename/extension if necessary.
(Back to top)(Next alert)
>>>>>

• Put the text you want shown between the square brackets [ ]
• Put the text of the URL between the round brackets ( )
• To grab the URL of the document to link, click the blue Share button and then copy link

>>>>> gd2md-html alert: inline image link here (to images/image12.png). Store image on your image server and adjust path/filename/extension if necessary.
(Back to top)(Next alert)
>>>>>

>>>>> gd2md-html alert: inline image link here (to images/image13.png). Store image on your image server and adjust path/filename/extension if necessary.
(Back to top)(Next alert)
>>>>>

• Edit the issue again to add a link to the new document
• Update the tracking spreadsheet with the issue number
  • To create a link in google sheets use the icon on the toolbar
• Prior to Product Management Communities of Practice meetings, or Project Team meetings, add a comment with a status update in the following format:
  • Progress: <include any relevant updates>
  • Blocks: <include anything that is causing a delay>
  • Availability: <include time you are available to discuss/work on the issue>
  • ETA: <include estimated date for completion>
• When you are ready to have the document reviewed, more it from In Progress (actively working) to Links/Questions/Review

>>>>> gd2md-html alert: inline image link here (to images/image14.png). Store image on your image server and adjust path/filename/extension if necessary.
(Back to top)(Next alert)
>>>>>

**Items **on the issue checklist

As you complete the items on the issue checklist, make sure to check the box to show progress.

List of items on the issue:

• Include project logo (top right)

• Overview

• History and or last 6 months

• Partners

• Roadmap/next 6 months

• Contact email

• Github URL

• Link to project page on hackforla.org

• Slack channel

• Last updated date

• Hack for LA logo (bottom right)

**Finalize **the One Sheet

Once leadership has signed off on the One Sheet it needs to be converted to PDF and added to the repository.

• To print to PDF, either click CTRL+P or go to the **File **menu and select **Print **from the drop down.
  *

>>>>> gd2md-html alert: inline image link here (to images/image15.png). Store image on your image server and adjust path/filename/extension if necessary.
(Back to top)(Next alert)
>>>>>

        * 

• When the dialog box pops up click on print, in the next dialog box, enter the name for the PDF and press save. The file naming format should be <Project nam>-Product-One-Sheet.PDF
  • Examples:
    • 100-Automations-Project-One-Sheet.pdf
    • BallotNav-Project-One-Sheet.pdf
    • Civic-Tech-Index-Product-One-Sheet.pdf

>>>>> gd2md-html alert: inline image link here (to images/image16.png). Store image on your image server and adjust path/filename/extension if necessary.
(Back to top)(Next alert)
>>>>>

• The PDF needs to be added to the Product One Sheets repository
• Refer to this guide on How to Do a Pull Request (For PMs) to complete the upload.

FAQ

Q: How often does the One Sheet get updated?

A: The One Sheet should be updated each quarter, and no longer than every 6 months.

Q: Why are there multiple versions of One Sheet?

A: The One Sheet reflects the project status at that time, and can be used to show progress and roadmap changes over time.

Q: What happens when the Product Managers are not responsive?

A: First, look on the Events Page to find out when the team is meeting and join their meeting to connect with active members. Second, reach out to the Slack Channel for the project instead of an individual. If all other attempts fail, discuss this blocker on the PM Community of Practice meeting.

[abenipa3]

@ExperimentsInHonesty Update: I found 2 ways to download the images from Google Docs.

The first one is to download the Doc as a Web Page as seen in the How To below. It will come as a zipped folder that contains the .HTML file and an images folder.

1. How to Download as a Web Page

In Docs, go to File > Download as > Web Page (.html, zipped).

Download the file, extract it on your desktop, and then navigate into the images folder, where you can find all of the images that were contained in the file.

Another alternative is to Publish to the web. One thing to note is when we make changes to the guide, it automatically updates every 5 minutes.

2. How to Publish to the web

In Docs, click on File > Publish to the web > Publish > OK.

On the next screen, you’ll get the public link to the Doc. Copy that, and open a new tab.

Preview of the Document in a New Tab

Paste in the link and go to the document. Right-click the image you want and choose “Save Image As”

Looking forward to talking more about it with the team on Wednesday. Thanks!

[ExperimentsInHonesty]

If we do option 1 above:
When we add the markdown file to the website, we put each in its own folder with the images from the download.

For example 2FA
Front matter in one file

---
title: 2FA Guide
description: Hack for LA requires two-factor authentication (2FA) in GitHub for all project contributors.
short-description: Hack for LA requires two-factor authentication (2FA) in GitHub for all project contributors.
in-this-guide: 
  - name: To Enable 2FA
    link: '#To-Enable-2FA'
  - name: FAQ
    link: '#FAQ'
card-type: guide-page
status: active
display: true
category: Development
svg: svg/2FA.svg
alt-text: 2fa-image
provider-link: '/guide-pages/2FA'
markdown: '/2FA/2FA.md'
images: '/2FA/images/'
---

WE are hoping for the format below, where the currents have the html under the front matter, we would have the markdown there, and the path to images would be specified in the front matter and we would remove the current path the markdown converter makes. For example

![alt_text](images/image1.png "image_tooltip")

turns into

![alt_text](image1.png "image_tooltip")

---
title: 2FA Guide
description: Hack for LA requires two-factor authentication (2FA) in GitHub for all project contributors.
short-description: Hack for LA requires two-factor authentication (2FA) in GitHub for all project contributors.
in-this-guide: 
  - name: To Enable 2FA
    link: '#To-Enable-2FA'
  - name: FAQ
    link: '#FAQ'
card-type: guide-page
status: active
display: true
category: Development
svg: svg/2FA.svg
alt-text: 2fa-image
provider-link: '/guide-pages/2FA'
images: '/assets/images/guides/[nameofguide]'
---
[REPLACE WITH ALL THE MARKDOWN CREATED]

[carolzjy]

Update from Alyssa (9/29): She's waiting for feedback from design team on our mockup.

[abenipa3]

Update: Received feedback from our design team and updated here. I apologize I wasn't able to attend on Monday. Will attend the meeting in the morning.

I also have the link to the Markdown Converter used for development but am unable to add it under Resources. Not sure if I have permission to edit since these are the options I'm seeing on the issue.

If anything, here is the link: https://workspace.google.com/u/0/marketplace/app/docs_to_markdown/700168918607?hl=en&pann=docs_addon_widget

[ExperimentsInHonesty]

Issue about using strong vs bold and em vs itallics https://help.siteimprove.com/support/solutions/articles/80000448460-accessibility-bold-vs-strong-and-italic-vs-emphasis - please discuss with design and potentially the developers on sunday

[ExperimentsInHonesty]

Please review this hackforla/knowledgebase-content#134

[ExperimentsInHonesty]

We want to be able to convert any text that shows up in double quotes, e.g. Enter "/Remind" into the field, into copy and paste text, e.g., Enter /Remind into the field

a method that replaces every double quote with backticks in the markdown

We want to be able to convert any text that shows up in double quotes, e.g. Enter "/Remind" into the field, into copy and paste text, e.g., Enter

/Remind

into the field

Ask Kristine if the copy bits in the design system pages have been accessibility tested. If no one has tested it, find the url for the pages and test it hackforla/website#1927 (comment)

[abenipa3]

Markdown Converter Documentation

The purpose is to record all findings in this comment as we test the converter and transition our WIP guides from Google Docs.

This documentation is added under Resources/Instructions for our convenience and will be continuously updated until we close this issue.

How Does Google Docs to Markdown Converter Work?

1. Install the Docs to Markdown from the G Suite Marketplace. (Link also included under Resources/Instructions.)
2. Open the Guide Document and click on Add-On -> Select Docs to Markdown -> Convert. [Preview Visual]
3. Wait for the extension to convert. Once it finished loading, the extension would like this:
   
4. Select Suppress Top Comment and then click on the Markdown button to generate.

What does Suppress Top Comment Do?

Suppress Top Comment deletes the information of the output, such as conversion notes, to minimize the time in making changes.

The information would look like the following:

<!-----
NEW: Check the "Suppress top comment" option to remove this info from the output.

Conversion time: 1.175 seconds.


Using this Markdown file:

1. Paste this output into your source file.
2. See the notes and action items below regarding this conversion run.
3. Check the rendered output (headings, lists, code blocks, tables) for proper
   formatting and use a linkchecker before you publish this page.

Conversion notes:

* Docs to Markdown version 1.0β31
* Wed Oct 13 2021 22:41:57 GMT-0700 (PDT)
* Source doc: Copy of Guide: How to Write a Guide
* This document has images: check for >>>>>  gd2md-html alert:  inline image link in generated source and store images to your server. NOTE: Images in exported zip file from Google Docs may not appear in  the same order as they do in your doc. Please check the images!


WARNING:
You have 9 H1 headings. You may want to use the "H1 -> H2" option to demote all headings by one level.

----->

5. Copy and paste the output into a new Markdown file.

How to Clean Up the Newly-Converted Markdown File?

1. Delete the error messages.

• The output may contain errors since images and font weights will not carry over.
• More details are in the following examples.

Example: How does the converter regards font-weights in titles?

Let's take the following title from our Google Docs as an example:

When we convert the Docs to Markdown, an error message as seen below will appear at the top of the output, which will affect the entire presentation of the guide: [Preview Visual]

<p style="color: red; font-weight: bold">>>>>>  gd2md-html alert:  ERRORs: 0; WARNINGs: 1; ALERTS: 8.</p>
<ul style="color: red; font-weight: bold"><li>See top comment block for details on ERRORs and WARNINGs. <li>In the converted Markdown or HTML, search for inline alerts that start with >>>>>  gd2md-html alert:  for specific instances that need correction.</ul>

<p style="color: red; font-weight: bold">Links to alert messages:</p><a href="#gdcalert1">alert1</a>
<a href="#gdcalert2">alert2</a>
<a href="#gdcalert3">alert3</a>
<a href="#gdcalert4">alert4</a>
<a href="#gdcalert5">alert5</a>
<a href="#gdcalert6">alert6</a>
<a href="#gdcalert7">alert7</a>
<a href="#gdcalert8">alert8</a>

<p style="color: red; font-weight: bold">>>>>> PLEASE check and correct alert issues and delete this message and the inline alerts.<hr></p>

Solution: Delete the error message. The output will now look more normal. [Preview Visual]

Example: How does the converter regards font-weights in headings and subheadings?

After the conversion, the output during the test showed that the converter did not regard the first word in the heading as bold as seen below. It adds an extra space before the closing asterisks.

A similar issue appears in the subheadings where the converter does not regard the text as a subheading.

The reason is that the converter added space in between the ## and the subheading as seen in the code below. However, it recognizes the bold in the first letter.

Solution: It is important to read the Markdown file to make all necessary changes in formatting.

Author's Note: It would be really nice to find out how to mitigate these occurrences to maximize team bandwidth in the near future.

Example: How does the converter regards images?

An error message will appear on each image that was placed on the Google Doc.

Solution: Delete the error message. Then save images and adjust the image paths.

2. To find out how to download images from Google Docs, please see the next section in How to Download Images from Google Docs

How to Download Images from Google Docs

There are two ways to download the images from Google Docs.

1. How to Download as a Web Page (Highly Recommended)

In Docs, go to File > Download as > Web Page (.html, zipped).

Download the file, extract it on your desktop, and then navigate into the images folder, where you can find all of the images that were contained in the file.

2. How to Publish to the web

In Docs, click on File > Publish to the web > Publish > OK.

On the next screen, you’ll get the public link to the Doc. Copy that, and open a new tab.

Preview of the Document in a New Tab

Paste in the link and go to the document. Right-click the image you want and choose “Save Image As”

Note for Publish to the web: When we make changes to the guide, it automatically updates every 5 minutes.

Google Docs to Markdown Converter - Q&A

1. How does the converter regard (extra) lines of spaces?

The Markdown File does not acknowledge extra spaces in the Guides. It automatically inputs one line of spaces between the headings/subheadings and the text. If we want to add extra lines, we would need to add <br>.

[Visual Example - Note: Just a test, so it's not visually appealing]

Lines of Spaces between the Headings/Subheadings and Steps

Based on the example below from a copy of How to Write a Guide, the converter adds a space in between the Subheadings and the Steps, even though the original version does not include it.

Original (from the Google Docs Version)

After converting into Markdown

The output displayed two lines of spaces in between as seen below. However, the extra spaces were not acknowledged after running the codes (through Jekyll).

The same applies to headings as well.

Alternatively, CSS will control the spaces between the headings/subheadings.

How to Locate "/Remind" and Convert into backticks

[@alyssabenipayo will insert more]

Additional Resources

Here are more resources to help better understand how the Docs to Markdown file work.

Links are also added to this issue under Resources/Instructions.

• Docs to Markdown Wiki

Tools Used for Testing

• Google Docs
• Docs to Markdown Converter
• Visual Studio Code
  • Prototype for Guides currently built with Jekyll.

[ExperimentsInHonesty]

we left comments last week for Alyssa here

and today's comments here

[ExperimentsInHonesty]

We reviewed and left her some notes: hackforla/website#1630 (comment)

[abenipa3]

Markdown Converter Documentation Update - 3/13/22

Summary:

As of January 8, 2022, the Docs to Markdown Converter released an update that removes error/warning messages called reckless mode. However, a message as seen below still appears at the top of the converted MD file and there are more issues encountered (mentioned in the next section) after converting the document.

New Issues Encountered

Images are not in the correct order

Expected Output

Actual Output

Backslashes appear randomly in the file

Solution

I created a Markdown Converter from scratch with Google Apps Script after gathering ideas from our Dev Team.

It is currently a basic converter that will do the following:

• Locate the Guide file by name (in this case How to Set Reminders in Slack) - Note: File must be in the same folder
  
  
• Runs and creates the following output:
  • Creates a new folder called "MDConverted" in the root drive, which contains all folders of all the outputs. Each output contains an image folder and the Markdown File. (Note the # in the title "Output-1647206918" is a timestamp in seconds, which can be adjusted if needed)
    
    
• If a developer would like to lessen the number of outputs generated after running the program, they can uncomment the code below // Creates 5 outputs. Outputs are automatically trashed after 5 files., which will "trash" outputs after running the code five times.
  

Future Features

There still needs to be more work done for the MD converter to be completed, so I created a new issue with what needs to be included in the Apps Script to further our progress: hackforla/website#2978

Availability

For this part of the project, I have 0 hours. I will focus on finishing the styling of the Guide Page at this time. (Will be busy the next two weeks with a freelance project and interviews.)