hackforla
Research and recommend best practice for using quotes around text in .md files
Overview
We need to research and recommend best practice so that we can audit the site to determine which quotes or lack of quotes need to be fixed.
Details
Here is an example of two text items in the same file.
https://github.com/hackforla/website/blob/gh-pages/.github/ISSUE_TEMPLATE/project-profile-card-review-and-update.yml?plain
https://github.com/hackforla/website/blob/271a82e89f55bdeeb80677403558228aee2bbe24/.github/ISSUE_TEMPLATE/project-profile-card-review-and-update.yml?plain=1#L224
https://github.com/hackforla/website/blob/271a82e89f55bdeeb80677403558228aee2bbe24/.github/ISSUE_TEMPLATE/project-profile-card-review-and-update.yml?plain=1#L233
Here are examples from two different project .md files. Notice that first one one uses a double quote and the second uses a single quote for the same type of link https://github.com/hackforla/website/blob/53e798a794d43ab507acf68f1ebbabf2a54b9bf0/_projects/food-oasis.md?plain=1#L90
https://github.com/hackforla/website/blob/53e798a794d43ab507acf68f1ebbabf2a54b9bf0/_projects/100-automations.md?plain=1#L53
Action Items
- [ ] Review .md and .yml files in the repository containing quotes and identify:
- [ ] What types of data are currently put in quotes
- [ ] Where the data in quotes is being used (to generate an HTML page, in an issue template, etc.)
- [ ] Research best practices for using quotes within .md/.yml files and any other files that pull quoted data from the .md/.yml files
- [ ] Write a comment on this issue with a recommendation for how quotes should be used in .md/.yml files, including:
- [ ] Types of data that should be in quotes, if any
- [ ] Whether single or double quotes should be used
- [ ] Brief explanation of your research findings and justification for your recommendations
- [ ] Finalize recommendations with a team lead
Additional Notes
Some research was already done for this issue and can be found in the comments, but it needs to be compiled into a concise recommendation. Additional research may be required.
Resources
- This Issue comes from this ER #7540
- Markdown single quotes
- Markdown double quotes
- YAML single quotes
- YAML double quotes
Hi @codyyjxn.
Please don't forget to add the proper labels to this issue. Currently, the labels for the following are missing:
- Feature
NOTE: Please ignore this comment if you do not have 'write' access to this directory.
To add a label, take a look at Github's documentation here.
Also, don't forget to remove the "missing labels" afterwards. To remove a label, the process is similar to adding a label, but you select a currently added label to remove it.
After the proper labels are added, the merge team will review the issue and add a "Ready for Prioritization" label once it is ready for prioritization.
Additional Resources:
![github-actions[bot] avatar](https://avatars.githubusercontent.com/in/15368?v=4 "Published by a pub.dev verified publisher"){kind=small}
There is an issue template for issues and an issue template for ER. This issue has an ER title, but is written as an issue. It needs to be written as an ER which outlines the problem, and defines the issues to be made. It can also include a solution outline or draft.
What is written above is a mashup of both. So I recommend you put a pause on this issue. Create an ER that outlines the issues that will need to be made. Get sign off on the approach, and then revise this issue to be the epic for the audit issues.
If that make sense go ahead, or if you want to discuss further, I am available on Sunday at the 10am meeting or Monday at 5pm at the dev/pm meeting.
@codyyjxn There is an issue template for issues and an issue template for ER. This issue has an ER title, but is written as an issue. It needs to be written as an ER which outlines the problem, and defines the issues to be made. It can also include a solution outline or draft.
What is written above is a mashup of both. So I recommend you put a pause on this issue. Create an ER that outlines the issues that will need to be made. Get sign off on the approach, and then revise this issue to be the epic for the audit issues.
If that make sense go ahead, or if you want to discuss further, I am available on Sunday at the 10am meeting or Monday at 5pm at the dev/pm meeting.
Hello @codyyjxn, we appreciate you taking on this issue, however it looks like you're already working on another issue at this time. Please wait until your current issue is merged before taking on another issue. :)
We are going to unassign you from this issue so you can focus on your current issue.
Hfla appreciates you! :)
Hi @codyyjxn, thank you for taking up this issue! Hfla appreciates you :)
Do let fellow developers know about your:- i. Availability: (When are you available to work on the issue/answer questions other programmers might have about your issue?) ii. ETA: (When do you expect this issue to be completed?)
You're awesome!
P.S. - You may not take up another issue until this issue gets merged (or closed). Thanks again :)
@codyyjxn
- when you are done drafting this issue. Add a
ready for prioritizationlabel to it. - I will take a look and see if we are ready to make the epic issue that would use these recommendations. See plan https://github.com/hackforla/website/issues/7540#issuecomment-2438436178
@codyyjxn I think you missed what you were supposed to do for this issue.
- write this issue so that it has action items that achieve the scope listed in the overview
We need to research and recommend best practice so that we can audit the site to determine which quotes or lack of quotes need to be fixed.
The current draft of the action items, tell the person to make the changes, which is premature given that no one has done the research and recommendations yet. I am not asking you to do the research and recommendations, but rather write an issue for someone to do it.
@codyyjxn I think you missed what you were supposed to do for this issue.
- write this issue so that it has action items that achieve the scope listed in the overview
We need to research and recommend best practice so that we can audit the site to determine which quotes or lack of quotes need to be fixed.
The current draft of the action items, tell the person to make the changes, which is premature given that no one has done the research and recommendations yet. I am not asking you to do the research and recommendations, but rather write an issue for someone to do it.
Got it! Thank you Bonnie!
@bonniewolfe Hi bonnie I have changed the instructions. I will attend todays meeting as well.
Hi @codyyjxn Bonnie asked me to help you work on this issue. I've rewritten the action items for you, basically this issue should just be to decide on a standard practice for using quotes in .md and .yml files. Once we have agreed on a standard, you'll create a new epic issue to audit files that may need to be changed.
- This is for the next step, but for an idea of what the epic issue will look like you can look at #5248.
Hi @DakuwoN, thank you for taking up this issue! Hfla appreciates you :)
Do let fellow developers know about your:- i. Availability: (When are you available to work on the issue/answer questions other programmers might have about your issue?) ii. ETA: (When do you expect this issue to be completed?)
You're awesome!
P.S. - You may not take up another issue until this issue gets merged (or closed). Thanks again :)
Availability: Monday - Sunday after 11AM until 7PM Central Time ETA: I should have this done by June 9th Monday.
@DakuwoN
Please add update using the below template (even if you have a pull request). Afterwards, remove the 'To Update !' label and add the 'Status: Updated' label.
- Progress: "What is the current status of your project? What have you completed and what is left to do?"
- Blockers: "Difficulties or errors encountered."
- Availability: "How much time will you have this week to work on this issue?"
- ETA: "When do you expect this issue to be completed?"
- Pictures (optional): "Add any pictures of the visual changes made to the site so far."
If you need help, be sure to either: 1) place your issue in the Questions/In Review column of the Project Board and ask for help at your next meeting, 2) put a "Status: Help Wanted" label on your issue and pull request, or 3) put up a request for assistance on the #hfla-site channel. Please note that including your questions in the issue comments- along with screenshots, if applicable- will help us to help you. Here and here are examples of well-formed questions.
You are receiving this comment because your last comment was before Tuesday, June 17, 2025 at 12:05 AM PST.
Hi @DakuwoN, for this issue you don't have to go through every single .md and .yml file, just take a look at some of them to get an idea of what they are used for and some of the specific instances where quotes appear. The main thing we want you to do is propose a standard for using quotes so that we can go through each of the files in a future issue and make sure they all adhere to the standard. You will probably have to do some research into the .md and .yml formats to see what function quotes serve and if there are documented standards for using them. Then based on your research and how you saw them used within hackforLA's files, write a recommendation for how we should use quotes in general. Here are a couple searches you can use to find some files to skim through:
https://github.com/search?q=repo%3Ahackforla%2Fwebsite+%22+%27+language%3AYAML&type=code https://github.com/search?q=repo%3Ahackforla%2Fwebsite+%22+%27+language%3AMarkdown+&type=code
On a cursory look, I would expect that there are at least some instances where quotes are definitely necessary, like when text contains symbols with meanings within Markdown, such as "#". Also consider whether there is a functional difference between single and double quotes or if we can simply choose one or the other for consistency.
Hopefully this helps, let me know if you need more guidance as you start to research.
Here are recommendations for using quotes in Markdown (.md) and YAML (.yaml/.yml) files:
Markdown (.md)
- Quotes in Text: Use straight double quotes "like this" or single quotes 'like this' for quoting text, following your style guide or English conventions.
- Code Blocks/Inline Code: Use backticks (`) for inline code or code blocks, not quotation marks.
- Blockquotes: For quoting other sources, use the Markdown blockquote syntax with > at the beginning of the line.
Example:
> "This is a quote from someone."
Here is some `inline code`.
YAML (.yml/.yaml)
- Unquoted Strings: Use unquoted strings when the value is simple (no special characters, no leading/trailing spaces, no reserved YAML keywords).
- Single Quotes (''): Use single quotes for strings that contain double quotes or special characters, or when you need the string to be interpreted literally.
- Double Quotes (""): Use double quotes when you need to include special characters (like \n for newline), escape sequences, or interpolation.
- Always Quote: Always quote values containing colons (:), leading/trailing spaces, or reserved words (e.g., yes, no, null).
- Consistency: Stick to one style throughout the file/project for consistency.
Example:
title: "Hack for LA's Website"
description: 'This YAML file uses single and double quotes appropriately.'
path: /some/path
note: "Use quotes if the string contains: colon, #, or special chars."
Summary Table
| When to Quote | Use Single Quotes | Use Double Quotes |
|---|---|---|
| Simple string | Not needed | Not needed |
| Contains single quote | Use double quotes | Use double quotes |
| Contains double quote | Use single quotes | Escape double quote (") |
| Needs escape sequences | Not supported | Supported |
| Reserved word/colon | Either | Either |
If your repo has a specific style guide, follow that. Otherwise, the above are widely accepted conventions. If you want to enforce this in your repository, consider using a linter like yamllint for YAML files.
In YAML and Markdown (.md) files, using quotes around data depends on the type of data and how you want it to be interpreted:
YAML:
- Strings with special characters: Use quotes if a string contains special characters (e.g., : { } [ ] , & * # ? | - < > = ! % @), or starts with a number, or includes spaces.
- Example:
"Hello, world!"
'2025-07-07'
- Example:
- Boolean or null-like values: Use quotes to avoid automatic type conversion (e.g., yes, no, on, off, null, true, false).
- Example:
"yes"(interpreted as a string, not boolean)
- Example:
- Strings with leading zeros: Use quotes to prevent YAML from interpreting them as numbers.
- Example:
"007"
- Example:
- Empty strings: Use quotes for clarity or to explicitly define an empty string.
- Example:
""
- Example:
You can use either single (' ') or double (" ") quotes in YAML. Double quotes allow for escape sequences (like \n), while single quotes do not.
Markdown (.md):
- Quotes are rarely required for data in Markdown, since it's primarily a markup language for text. If you're embedding code, configuration, or YAML front matter, follow the YAML rules above.
Summary Table:
| Type of data | Use quotes? | Example |
|---|---|---|
| Special characters | Yes | "foo:bar" |
| Boolean-like strings | Yes | "no" |
| Leading zeros | Yes | "0123" |
| Numbers (actual numbers) | No | 123 |
| Simple words | No (optional) | hello |
| Empty string | Yes | "" |
Tip:
When in doubt, use quotes in YAML to ensure your data is interpreted as a string. For Markdown, only use quotes if you want to display them as part of the text or in code blocks.
There is no universal standard for using single or double quotes in Markdown (.md) or YAML (.yml/.yaml) files—both are valid, but conventions may vary by project.
Markdown (.md):
- Quotes are typically used in code blocks, frontmatter, or inline code, and both single and double quotes are acceptable.
- Consistency is most important. There is no strict rule enforced by Markdown itself.
YAML (.yml/.yaml):
- Both single and double quotes are allowed for strings.
- Single quotes: 'string'
- Double quotes: "string"
- Use quotes if your string contains special characters, spaces at the beginning/end, or YAML-reserved characters (like :, ?, -, etc.).
- Double quotes allow for escape sequences (e.g., \n, \t), while single quotes do not.
Best Practice:
Follow the convention already used in your project for consistency. If the repo has a linter (like yamllint or prettier) or a style guide, check those for specific rules.
Hello, so I used the web and also Github Copilot to help with my research results. They both gave similar results, the web was a little more hard to follow as so many different people had different opinions on this matter. It seems to be very subjective as when to use quotes or no quotes as well as single quotes or double quotes, it's a lot of this and that and different tradeoffs/arguments it appears. However, we could follow some traditional conventions that are used as best practices, and make this consistent throughout the repository. They are posted above. It could really depend on project needs and how a particular team wants to implement these concepts.
@DakuwoN
Please add update using the below template (even if you have a pull request). Afterwards, remove the '2 weeks inactive' label and add the 'Status: Updated' label.
- Progress: "What is the current status of your project? What have you completed and what is left to do?"
- Blockers: "Difficulties or errors encountered."
- Availability: "How much time will you have this week to work on this issue?"
- ETA: "When do you expect this issue to be completed?"
- Pictures (optional): "Add any pictures of the visual changes made to the site so far."
If you need help, be sure to either: 1) place your issue in the Questions/In Review column of the Project Board and ask for help at your next meeting, 2) put a "Status: Help Wanted" label on your issue and pull request, or 3) put up a request for assistance on the #hfla-site channel. Please note that including your questions in the issue comments- along with screenshots, if applicable- will help us to help you. Here and here are examples of well-formed questions.
You are receiving this comment because your last comment was before Tuesday, July 29, 2025 at 12:09 AM PST.
Hi @michael-4, thank you for taking up this issue! Hfla appreciates you :)
Do let fellow developers know about your:- i. Availability: (When are you available to work on the issue/answer questions other programmers might have about your issue?) ii. ETA: (When do you expect this issue to be completed?)
You're awesome!
P.S. - You may not take up another issue until this issue gets merged (or closed). Thanks again :)