Add documentation (markup syntax, features, other projects)

[SpotlightKid]

General information

• Device: Acer B3-A30
• Android Version: Android 6.0
• App version: v0.1.5

Expected result

It would be very helpful to have some kind of Markdown syntax reference in the app, which is quickly accessible from within the edit view. E.g. via a button on the editing toolbar or the application toolbar (next to the preview and share buttons).

This could be simply a flat document, e.g. copied/adapted from this one, but it should also list any Markdown extension, which are enabled, and link to appropriate documentation (some inspiration might be gleaned from here).

Getting back to editing the current document should be possible with one or two taps.

[gsantner]

Best would be if there is some free markdown guide that is already translated into many languages. English may be nice, but to learn new things it's better to have it in own language

[curtisy1]

Not sure if there's a broad collection of languages available, but the various Markdown Cheatsheets would be ideal for this probably. The most full fledged one I found is probably this, while GitHub also provides a pdf you can include here.

Translating would probably be best done as a community project via pull requests in that case though.

[gsantner]

Gopd idea, I see just one problem, that are both are too focused on GitHub/GFM, which extensions are not all supported by commonmark-parser.

Do you think its better to deliver cheatsheet document(s) with markor, or just link externally to it?

[curtisy1]

Do you think its better to deliver cheatsheet document(s) with markor, or just link externally to it?

That's a good question. I'd probably go with the first option and add the contents of http://commonmark.org/help/ in a separate document either in About or via the navigation bar in edit mode (although I prefer the first).

Alternatively, markor could provide a "dummy" document on first startup, that has all supported formats included. This would then be handled by a popup, asking the user if he/she wants to view the documentation or not.

[SpotlightKid]

Two important points here:

• to be really helpful, at least the syntax reference part of the documentation should be quickly accessible from the editing view, i.e. without, for example, having to go back to the document browser first.
• because there are so many different varieties of Markdown, it is important to document exactly, which non-standard syntax extension are supported by Markor.

[curtisy1]

@gsantner Would you say this is a good issue to get started in Android Development? Because I'd be willing to have a try at this. I'm fluent in C#, so Java shouldn't be much of a hindrance. The only critical point would probably be time (since I'm only able to work on this in the evening and on weekends).

[gsantner]

This is mostly research of available markdown guides/documents/examples. (Or/And creating custom ones for this purpose)

On Android part there is not too much todo, beside adding maybe an menu-option/layout row/box, which should be possible without knowing Android dev in advance.

[curtisy1]

Alright, I shall have a try then.

Thanks!

[gsantner]

@curtisy1 Did you find some good doc/guide/documents that could be useable?

[curtisy1]

@gsantner not really. I'm mainly focusing on creating a custom document for now as this would be the easiest way probably

[gsantner]

ok, hers what I used for screenshot, maybe you can reuse something from it.

## Markor
Markdown Texteditor for notes and files. Simple and lightweight.  
📝 Write down __notes and ideas__  
🖍 Edit textfiles in **markdown** format  
📚 `Notebook in Documents` or custom folder  
📖 Notebook with subfolder support  
📄 Edit markdown files from other apps  
👀 Preview rendered markdown  
🔲 ~~Black~~ Dark and Light theme  
📜 Allows to set language other than system setting

![Markor Logo](https://raw.githubusercontent.com/gsantner/markor/master/app/src/main/ic_launcher-web.png)

> quote
> 

1. task
2. task

- todo
- todo

[SpotlightKid]

Btw, here is the list of currently enabled syntax extensions:

https://github.com/gsantner/markor/blob/master/app/src/main/java/net/gsantner/markor/format/converter/MarkdownConverter.java#L61

Follow the link in the source code comment there to see a short description of each extension, from which you can probably just copy and paste what you need. Maybe include a link back to the README in your documentas a courtesy.

[gsantner]

I think of adding a list of helpful content / references, in markdown format. I also think of making it just a single markdown file resource, untranslateable. This makes managing these things a lot easier. Anyway, referenced sites will be mostly in one language (and not available for all languages that markor supports), most likely english. Translating website-titles doesn't make any sense anyway. I think of making it quite like the CONTRIBUTORS.md file.

If somebody has some links and references, just plainly post them here as comments

[gsantner]

Hi everybody, I just retitled the issue a little. This is not about markdown only anymore, but in general about adding (user) documenation to the project.