This is part 2 of a series of posts I'm planning to write while I'm building my open source side-project: Submitter. I'll be writing regularly(hopefully) about my work including all the challenges I came through.
Previous post: Submission friendly projects: Introduction
The Format
The core idea behind the project is to make submitting issues/PRs easier by rendering their templates in an interactive way. Below, I'm going to describe the things that I think could be improved when we render the template, your thoughts are welcome!
NOTE: The format should be compatible with GitHub Flavored Markdown specification.
Task Lists:
You can write task lists in GitHub like this:
- [x] something
- [ ] something else
Or this:
* [x] something
* [ ] something else
Or this:
+ [x] something
+ [ ] something else
Or even as an ordered task list:
1. [x] something
2. [ ] something else
Technically, the ordered lists are rendered as
<ol>
in HTML, but GitHub's stylesheet removes the numbers.
All of the above lists will produce the same output (checkboxes):
While rendering task lists as checkboxes are cool, sometimes it makes more sense to use radio buttons to render task lists, e.g:
I'm submitting:
- [ ] A bug
- [ ] A feature request
But we need to determine how to write radio button lists. I'd prefer to use *
to indicate radio button lists and use -
,+
, and numbers to indicate normal task lists. e.g:
* [ ] something
* [ ] something else
Will be rendered as:
<input type="radio"> something </br>
<input type="radio"> something else </br>
NOTE: because list item values may get so complex , we can't use dropdown (i.e.
<select>
) to render them as they may contain @mentions, #refs, links ...etc.
However, I'll need a markdown parser that provides the info of what character used as unordered list indicator (i.e. -
or *
)? However, all parsers I know don't! For that reason, I may find myself in a situation either to write my own markdown parser or use a different approach for example, ordered task list?
Markdown inputs
Rendering the issue/PR template as HTML makes it necessary to provide a way to insert markdown input. We will use the following pattern:
# Description
(description goes here)
For the above example we will render a <textarea>
(that has markdown support) as follows:
<h1>Description<h1>
<textarea placeholder="description goes here"></textarea>
Later when the user submits the form, we will parse the input in the <textarea>
as markdown and inject it in the final markdown document.
Of course, you can't use markdown ..etc between (
and )
. If you want to tell the user something use normal markdown before the input pattern e.g:
# Description
Read this [guide]() to know how to write a good description.
(description goes here)
Comments
Issue/PR template authors usually use HTML comments to guide you through the templates. But, because they're comments, they won't be visible when we render the template. A possible solution is to render them as <blockquote>
s e.g:
<!-- use x instead of y -->
Will be rendered to:
<blockquote>use x instead of y</blockquote>
Show/hide sections
When using GitHub issues to report different types of issues i.e. bugs, feature requests, questions ..etc you may find there is type-specific information that isn't related to other types, for example, the version number isn't necessary for feature request issues.
In that case, a show/hide capability would be nice to have. However, I've no idea for now how to implement this feature, so I will ignore it for now and keep things simple. If you have an idea you'd like to share go ahead.
The stack
I will be using the following technologies/products to implement the project, I never used some of them, so it's a good chance to learn:
- Auth0 for authentication
- Koa for server-side logic
- Next.js for server-side rendered React
- Now for hosting.
- And of course GitHub!
Edited: The project source code is available in ahmed-taj/submitter. It only contains initial setup right now!
More posts are coming!
Thank you :)
Latest comments (2)
Great!!!
But will be a cli tool or a little web application?
A little web application for now
And yes! it could be a CLI too, but currently I've to focus on getting the initial release of the web version working. Then I may start the CLI