From d1c2ea5efae09f4e9ea4a756cfc16e56bb74c599 Mon Sep 17 00:00:00 2001 From: nytpu Date: Tue, 8 Sep 2020 16:41:40 -0600 Subject: [PATCH 1/5] changed to relative links --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 2343569..7daac89 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,6 @@ 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 ## Table of Contents -[gemlog](https://tildegit.org/swiftmandolin/gemini-style-guide/src/branch/master/gemlog.md) +[gemlog](gemlog.md) To contribute, please see [the contribution guide](https://tildegit.org/swiftmandolin/gemini-style-guide/src/branch/master/CONTRIBUTING.md) -- 2.34.1 From 2662430f8fa2b5fb73b2d3a7f8701ac2950cd0b7 Mon Sep 17 00:00:00 2001 From: nytpu Date: Tue, 8 Sep 2020 16:58:43 -0600 Subject: [PATCH 2/5] added general best practices page --- README.md | 1 + general-practices.md | 34 ++++++++++++++++++++++++++++++++++ 2 files changed, 35 insertions(+) create mode 100644 general-practices.md diff --git a/README.md b/README.md index 7daac89..28d1707 100644 --- a/README.md +++ b/README.md @@ -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 ## Table of Contents +[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) diff --git a/general-practices.md b/general-practices.md new file mode 100644 index 0000000..ea56224 --- /dev/null +++ b/general-practices.md @@ -0,0 +1,34 @@ +# General Best Practices + +## File Naming +Filenames should use '-' to replace spaces, and should have no special characters (alphanumeric & dashes only). 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 (i.e. '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 + -- 2.34.1 From 2532ed55d5403a49aa3efd055d2e307628a33609 Mon Sep 17 00:00:00 2001 From: nytpu Date: Tue, 8 Sep 2020 16:59:01 -0600 Subject: [PATCH 3/5] fixed formatting issue --- CONTRIBUTING.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fa77e28..d3ff944 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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. I only have a few rules for formatting which I'll explain below: + - Use `##` for each section - Use `###` for the subsection headers - Provide a rule -- 2.34.1 From 7eb5a65dec65c4fc2d9da3ae7a44d4889739ba0a Mon Sep 17 00:00:00 2001 From: nytpu Date: Tue, 8 Sep 2020 17:11:10 -0600 Subject: [PATCH 4/5] added more details to title section --- gemlog.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/gemlog.md b/gemlog.md index c262d90..b093efe 100644 --- a/gemlog.md +++ b/gemlog.md @@ -12,7 +12,7 @@ This allows proper sorting while also being able to quickly see what content is ``` ## 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 Besides # denoting h1, which is common for titles, the single space afterwards looks nice if the gemini client does not render the #. -- 2.34.1 From 2d4211032615e2ff0abad44f0af28ba152908443 Mon Sep 17 00:00:00 2001 From: nytpu Date: Tue, 8 Sep 2020 17:13:02 -0600 Subject: [PATCH 5/5] fixed typos and needless information --- general-practices.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/general-practices.md b/general-practices.md index ea56224..80dc923 100644 --- a/general-practices.md +++ b/general-practices.md @@ -1,7 +1,7 @@ # General Best Practices ## File Naming -Filenames should use '-' to replace spaces, and should have no special characters (alphanumeric & dashes only). 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 (i.e. 'hello-world.gmi' and 'HELLO-WORLD.gmi') +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. -- 2.34.1