Added "General Best Practices" page and fixed minor formatting issues (#1)
fixed typos and needless information added more details to title section fixed formatting issue added general best practices page changed to relative links Reviewed-on: #1
This commit is contained in:
parent
6795cbf4e6
commit
513584f368
|
@ -5,6 +5,7 @@ The most important aspect for contributing to this is to discuss what should be
|
||||||
To submit changes, please open a pull request (after forking) and submit your changes.
|
To submit changes, please open a pull request (after forking) and submit your changes.
|
||||||
|
|
||||||
I only have a few rules for formatting which I'll explain below:
|
I only have a few rules for formatting which I'll explain below:
|
||||||
|
|
||||||
- Use `##` for each section
|
- Use `##` for each section
|
||||||
- Use `###` for the subsection headers
|
- Use `###` for the subsection headers
|
||||||
- Provide a rule
|
- Provide a rule
|
||||||
|
|
|
@ -6,6 +6,7 @@ Reading nytpu's post (1) on formatting definitely got me thinking about formatti
|
||||||
|
|
||||||
(2): gemini://gemini.circumlunar.space/~swiftmandolin/gemlog/2020-09-07-re-experimenting-with-ways-to-format-documents-on-gemini.gmi
|
(2): gemini://gemini.circumlunar.space/~swiftmandolin/gemlog/2020-09-07-re-experimenting-with-ways-to-format-documents-on-gemini.gmi
|
||||||
## Table of Contents
|
## Table of Contents
|
||||||
[gemlog](https://tildegit.org/swiftmandolin/gemini-style-guide/src/branch/master/gemlog.md)
|
[general best practices](general-practices.md)
|
||||||
|
[gemlog](gemlog.md)
|
||||||
|
|
||||||
To contribute, please see [the contribution guide](https://tildegit.org/swiftmandolin/gemini-style-guide/src/branch/master/CONTRIBUTING.md)
|
To contribute, please see [the contribution guide](https://tildegit.org/swiftmandolin/gemini-style-guide/src/branch/master/CONTRIBUTING.md)
|
||||||
|
|
|
@ -12,7 +12,7 @@ This allows proper sorting while also being able to quickly see what content is
|
||||||
```
|
```
|
||||||
|
|
||||||
## Title
|
## Title
|
||||||
All gemlogs should contain a title denoted by a single `#` with one whitespace afterwards, then the title.
|
All gemlogs should contain a title denoted by a single `#` with one whitespace afterwards, then the title. The title doesn't have to be the first line, but it should be the first header in the document.
|
||||||
|
|
||||||
### Why
|
### Why
|
||||||
Besides # denoting h1, which is common for titles, the single space afterwards looks nice if the gemini client does not render the #.
|
Besides # denoting h1, which is common for titles, the single space afterwards looks nice if the gemini client does not render the #.
|
||||||
|
|
|
@ -0,0 +1,34 @@
|
||||||
|
# General Best Practices
|
||||||
|
|
||||||
|
## File Naming
|
||||||
|
Filenames should use '-' to replace spaces, and should have no special characters. Gemtext documents should have the extension `.gmi` or `.gemini`. Mixed case can be used, but if you are on a case sensitive filesystem (ext4, etc) you should not have 2 files with the same name and different cases (e.g. 'hello-world.gmi' and 'HELLO-WORLD.gmi')
|
||||||
|
|
||||||
|
### Why
|
||||||
|
This follows the convention for the web and ensures compatibility with most filesystems. Dashes are preferred to underscores as a separator because underscores can be hidden by an underline if a client underlines links.
|
||||||
|
|
||||||
|
### Example
|
||||||
|
```
|
||||||
|
my-cool-page.gmi
|
||||||
|
```
|
||||||
|
|
||||||
|
## Preformatted alt text
|
||||||
|
The alt text after the opening preformatted text line (`````text here``) should be used as an alt text describing the content if it is not machine-readable. For instance, ASCII art should have a brief description in the alt text, but a code block does not need alt text.
|
||||||
|
|
||||||
|
### Why
|
||||||
|
This ensures that people using gemini with something like a screen reader are able to understand all the aspects of the site.
|
||||||
|
|
||||||
|
### Example
|
||||||
|
```ascii banner saying "ART"
|
||||||
|
_ ____ _____
|
||||||
|
/ \ | _ \_ _|
|
||||||
|
/ _ \ | |_) || |
|
||||||
|
/ ___ \| _ < | |
|
||||||
|
/_/ \_\_| \_\|_|
|
||||||
|
```
|
||||||
|
|
||||||
|
## Links
|
||||||
|
TODO: probably similar to gemlog links
|
||||||
|
|
||||||
|
## Navigation
|
||||||
|
TODO: probably similar to gemlog links with some modifications
|
||||||
|
|
Loading…
Reference in New Issue