From 33c431f734fd1f991f92240818a4d650b133b063 Mon Sep 17 00:00:00 2001 From: nathanlesage Date: Sun, 8 Sep 2019 18:19:19 +0200 Subject: [PATCH] Enable multi-language docs --- README.md | 31 +- {docs/assets => assets}/app.css | 2 +- assets/index.html | 66 +++ config/de.yml | 62 +++ mkdocs.yml => config/en.yml | 13 +- docs/{ => de}/5-minutes.md | 0 docs/{ => de}/academic/citations.md | 0 docs/{ => de}/academic/custom-templates.md | 0 docs/{ => de}/academic/pomodoro.md | 0 docs/{ => de}/academic/presentations.md | 0 docs/{ => de}/academic/projects.md | 0 docs/{ => de}/academic/readability.md | 0 docs/{ => de}/academic/zkn-method.md | 0 docs/de/assets/app.css | 1 + docs/{ => de}/core/attachments.md | 0 docs/{ => de}/core/custom-css.md | 0 docs/{ => de}/core/editor.md | 0 docs/{ => de}/core/export.md | 0 docs/{ => de}/core/file-list.md | 0 docs/{ => de}/core/localisation.md | 0 docs/{ => de}/core/search.md | 0 docs/{ => de}/core/tables.md | 0 docs/{ => de}/core/virtual-directories.md | 0 docs/{ => de}/faq.md | 0 docs/{ => de}/get-involved.md | 0 docs/{ => de}/guides/guide-ide.md | 0 docs/{ => de}/guides/guide-notes.md | 0 docs/{ => de}/guides/guide-zettelkasten.md | 0 .../img/attachment-pane-references.png | Bin docs/{ => de}/img/attachment_sidebar.png | Bin .../img/attachment_sidebar_images.png | Bin docs/{ => de}/img/back.png | Bin docs/{ => de}/img/create.png | Bin docs/{ => de}/img/create_tex_file.png | Bin docs/{ => de}/img/custom_css_pilcrow.png | Bin docs/{ => de}/img/custom_css_unsplash.png | Bin docs/{ => de}/img/export-to-csl-json.png | Bin docs/{ => de}/img/export.png | Bin docs/{ => de}/img/file_meta.png | Bin docs/{ => de}/img/long_markdown_table.png | Bin docs/{ => de}/img/markdown.png | Bin docs/{ => de}/img/open.png | Bin docs/{ => de}/img/pdf_settings_font.png | Bin docs/{ => de}/img/pomodoro_init.png | Bin docs/{ => de}/img/pomodoro_run.png | Bin docs/{ => de}/img/presentations_scripts.png | Bin docs/{ => de}/img/presentations_styles.png | Bin docs/{ => de}/img/project_directory.png | Bin docs/{ => de}/img/settings_advanced.png | Bin docs/{ => de}/img/settings_display.png | Bin docs/{ => de}/img/settings_editor.png | Bin docs/{ => de}/img/settings_export.png | Bin docs/{ => de}/img/settings_general.png | Bin docs/{ => de}/img/settings_project.png | Bin docs/{ => de}/img/settings_zettelkasten.png | Bin docs/{ => de}/img/sorting_indicators.png | Bin docs/{ => de}/img/table_active_cell.png | Bin docs/{ => de}/img/table_with_edge_buttons.png | Bin docs/{ => de}/img/tags_settings.png | Bin docs/{ => de}/img/translations_list.png | Bin docs/{ => de}/img/writing_targets.png | Bin .../{ => de}/img/writing_targets_settings.png | Bin docs/{ => de}/img/zettlr_ide.png | Bin docs/{ => de}/img/zettlr_notes.png | Bin docs/{ => de}/img/zettlr_table.png | Bin docs/{ => de}/img/zettlr_table_movement.png | Bin docs/{ => de}/img/zettlr_zettelkasten.png | Bin docs/{ => de}/img/zettlt_tex_file.png | Bin docs/{ => de}/index.md | 0 docs/{ => de}/install.md | 0 docs/{ => de}/reference/markdown-basics.md | 0 docs/{ => de}/reference/settings.md | 0 docs/{ => de}/reference/shortcuts.md | 0 docs/{ => de}/reference/spell-checking.md | 0 docs/en/5-minutes.md | 69 +++ docs/en/academic/citations.md | 95 ++++ docs/en/academic/custom-templates.md | 113 +++++ docs/en/academic/pomodoro.md | 39 ++ docs/en/academic/presentations.md | 125 +++++ docs/en/academic/projects.md | 48 ++ docs/en/academic/readability.md | 45 ++ docs/en/academic/zkn-method.md | 37 ++ docs/en/assets/app.css | 1 + docs/en/core/attachments.md | 27 ++ docs/en/core/custom-css.md | 437 ++++++++++++++++++ docs/en/core/editor.md | 70 +++ docs/en/core/export.md | 30 ++ docs/en/core/file-list.md | 75 +++ docs/en/core/localisation.md | 36 ++ docs/en/core/search.md | 53 +++ docs/en/core/tables.md | 99 ++++ docs/en/core/virtual-directories.md | 28 ++ docs/en/faq.md | 90 ++++ docs/en/get-involved.md | 156 +++++++ docs/en/guides/guide-ide.md | 40 ++ docs/en/guides/guide-notes.md | 63 +++ docs/en/guides/guide-zettelkasten.md | 33 ++ docs/en/img/attachment-pane-references.png | Bin 0 -> 265018 bytes docs/en/img/attachment_sidebar.png | Bin 0 -> 264466 bytes docs/en/img/attachment_sidebar_images.png | Bin 0 -> 458573 bytes docs/en/img/back.png | Bin 0 -> 227061 bytes docs/en/img/create.png | Bin 0 -> 416112 bytes docs/en/img/create_tex_file.png | Bin 0 -> 34046 bytes docs/en/img/custom_css_pilcrow.png | Bin 0 -> 92207 bytes docs/en/img/custom_css_unsplash.png | Bin 0 -> 4437582 bytes docs/en/img/export-to-csl-json.png | Bin 0 -> 185327 bytes docs/en/img/export.png | Bin 0 -> 42935 bytes docs/en/img/file_meta.png | Bin 0 -> 30818 bytes docs/en/img/long_markdown_table.png | Bin 0 -> 201948 bytes docs/en/img/markdown.png | Bin 0 -> 206950 bytes docs/en/img/open.png | Bin 0 -> 2860150 bytes docs/en/img/pdf_settings_font.png | Bin 0 -> 265644 bytes docs/en/img/pomodoro_init.png | Bin 0 -> 125331 bytes docs/en/img/pomodoro_run.png | Bin 0 -> 117850 bytes docs/en/img/presentations_scripts.png | Bin 0 -> 49036 bytes docs/en/img/presentations_styles.png | Bin 0 -> 104200 bytes docs/en/img/project_directory.png | Bin 0 -> 6055 bytes docs/en/img/settings_advanced.png | Bin 0 -> 226611 bytes docs/en/img/settings_display.png | Bin 0 -> 129261 bytes docs/en/img/settings_editor.png | Bin 0 -> 320249 bytes docs/en/img/settings_export.png | Bin 0 -> 194748 bytes docs/en/img/settings_general.png | Bin 0 -> 177968 bytes docs/en/img/settings_project.png | Bin 0 -> 143213 bytes docs/en/img/settings_zettelkasten.png | Bin 0 -> 253981 bytes docs/en/img/sorting_indicators.png | Bin 0 -> 39795 bytes docs/en/img/table_active_cell.png | Bin 0 -> 232277 bytes docs/en/img/table_with_edge_buttons.png | Bin 0 -> 234649 bytes docs/en/img/tags_settings.png | Bin 0 -> 195584 bytes docs/en/img/translations_list.png | Bin 0 -> 181675 bytes docs/en/img/writing_targets.png | Bin 0 -> 15651 bytes docs/en/img/writing_targets_settings.png | Bin 0 -> 29811 bytes docs/en/img/zettlr_ide.png | Bin 0 -> 1113613 bytes docs/en/img/zettlr_notes.png | Bin 0 -> 482131 bytes docs/en/img/zettlr_table.png | Bin 0 -> 198519 bytes docs/en/img/zettlr_table_movement.png | Bin 0 -> 244983 bytes docs/en/img/zettlr_zettelkasten.png | Bin 0 -> 568388 bytes docs/en/img/zettlt_tex_file.png | Bin 0 -> 611710 bytes docs/en/index.md | 51 ++ docs/en/install.md | 99 ++++ docs/en/reference/markdown-basics.md | 129 ++++++ docs/en/reference/settings.md | 181 ++++++++ docs/en/reference/shortcuts.md | 97 ++++ docs/en/reference/spell-checking.md | 38 ++ docs/img/.DS_Store | Bin 6148 -> 0 bytes scripts/build.sh | 19 + scripts/serve.sh | 19 + 146 files changed, 2602 insertions(+), 15 deletions(-) rename {docs/assets => assets}/app.css (96%) create mode 100644 assets/index.html create mode 100644 config/de.yml rename mkdocs.yml => config/en.yml (84%) rename docs/{ => de}/5-minutes.md (100%) rename docs/{ => de}/academic/citations.md (100%) rename docs/{ => de}/academic/custom-templates.md (100%) rename docs/{ => de}/academic/pomodoro.md (100%) rename docs/{ => de}/academic/presentations.md (100%) rename docs/{ => de}/academic/projects.md (100%) rename docs/{ => de}/academic/readability.md (100%) rename docs/{ => de}/academic/zkn-method.md (100%) create mode 120000 docs/de/assets/app.css rename docs/{ => de}/core/attachments.md (100%) rename docs/{ => de}/core/custom-css.md (100%) rename docs/{ => de}/core/editor.md (100%) rename docs/{ => de}/core/export.md (100%) rename docs/{ => de}/core/file-list.md (100%) rename docs/{ => de}/core/localisation.md (100%) rename docs/{ => de}/core/search.md (100%) rename docs/{ => de}/core/tables.md (100%) rename docs/{ => de}/core/virtual-directories.md (100%) rename docs/{ => de}/faq.md (100%) rename docs/{ => de}/get-involved.md (100%) rename docs/{ => de}/guides/guide-ide.md (100%) rename docs/{ => de}/guides/guide-notes.md (100%) rename docs/{ => de}/guides/guide-zettelkasten.md (100%) rename docs/{ => de}/img/attachment-pane-references.png (100%) rename docs/{ => de}/img/attachment_sidebar.png (100%) rename docs/{ => de}/img/attachment_sidebar_images.png (100%) rename docs/{ => de}/img/back.png (100%) rename docs/{ => de}/img/create.png (100%) rename docs/{ => de}/img/create_tex_file.png (100%) rename docs/{ => de}/img/custom_css_pilcrow.png (100%) rename docs/{ => de}/img/custom_css_unsplash.png (100%) rename docs/{ => de}/img/export-to-csl-json.png (100%) rename docs/{ => de}/img/export.png (100%) rename docs/{ => de}/img/file_meta.png (100%) rename docs/{ => de}/img/long_markdown_table.png (100%) rename docs/{ => de}/img/markdown.png (100%) rename docs/{ => de}/img/open.png (100%) rename docs/{ => de}/img/pdf_settings_font.png (100%) rename docs/{ => de}/img/pomodoro_init.png (100%) rename docs/{ => de}/img/pomodoro_run.png (100%) rename docs/{ => de}/img/presentations_scripts.png (100%) rename docs/{ => de}/img/presentations_styles.png (100%) rename docs/{ => de}/img/project_directory.png (100%) rename docs/{ => de}/img/settings_advanced.png (100%) rename docs/{ => de}/img/settings_display.png (100%) rename docs/{ => de}/img/settings_editor.png (100%) rename docs/{ => de}/img/settings_export.png (100%) rename docs/{ => de}/img/settings_general.png (100%) rename docs/{ => de}/img/settings_project.png (100%) rename docs/{ => de}/img/settings_zettelkasten.png (100%) rename docs/{ => de}/img/sorting_indicators.png (100%) rename docs/{ => de}/img/table_active_cell.png (100%) rename docs/{ => de}/img/table_with_edge_buttons.png (100%) rename docs/{ => de}/img/tags_settings.png (100%) rename docs/{ => de}/img/translations_list.png (100%) rename docs/{ => de}/img/writing_targets.png (100%) rename docs/{ => de}/img/writing_targets_settings.png (100%) rename docs/{ => de}/img/zettlr_ide.png (100%) rename docs/{ => de}/img/zettlr_notes.png (100%) rename docs/{ => de}/img/zettlr_table.png (100%) rename docs/{ => de}/img/zettlr_table_movement.png (100%) rename docs/{ => de}/img/zettlr_zettelkasten.png (100%) rename docs/{ => de}/img/zettlt_tex_file.png (100%) rename docs/{ => de}/index.md (100%) rename docs/{ => de}/install.md (100%) rename docs/{ => de}/reference/markdown-basics.md (100%) rename docs/{ => de}/reference/settings.md (100%) rename docs/{ => de}/reference/shortcuts.md (100%) rename docs/{ => de}/reference/spell-checking.md (100%) create mode 100755 docs/en/5-minutes.md create mode 100755 docs/en/academic/citations.md create mode 100644 docs/en/academic/custom-templates.md create mode 100755 docs/en/academic/pomodoro.md create mode 100755 docs/en/academic/presentations.md create mode 100755 docs/en/academic/projects.md create mode 100644 docs/en/academic/readability.md create mode 100755 docs/en/academic/zkn-method.md create mode 120000 docs/en/assets/app.css create mode 100644 docs/en/core/attachments.md create mode 100755 docs/en/core/custom-css.md create mode 100755 docs/en/core/editor.md create mode 100755 docs/en/core/export.md create mode 100755 docs/en/core/file-list.md create mode 100755 docs/en/core/localisation.md create mode 100644 docs/en/core/search.md create mode 100644 docs/en/core/tables.md create mode 100755 docs/en/core/virtual-directories.md create mode 100755 docs/en/faq.md create mode 100755 docs/en/get-involved.md create mode 100755 docs/en/guides/guide-ide.md create mode 100755 docs/en/guides/guide-notes.md create mode 100755 docs/en/guides/guide-zettelkasten.md create mode 100644 docs/en/img/attachment-pane-references.png create mode 100644 docs/en/img/attachment_sidebar.png create mode 100644 docs/en/img/attachment_sidebar_images.png create mode 100644 docs/en/img/back.png create mode 100644 docs/en/img/create.png create mode 100644 docs/en/img/create_tex_file.png create mode 100755 docs/en/img/custom_css_pilcrow.png create mode 100644 docs/en/img/custom_css_unsplash.png create mode 100644 docs/en/img/export-to-csl-json.png create mode 100644 docs/en/img/export.png create mode 100644 docs/en/img/file_meta.png create mode 100644 docs/en/img/long_markdown_table.png create mode 100644 docs/en/img/markdown.png create mode 100644 docs/en/img/open.png create mode 100644 docs/en/img/pdf_settings_font.png create mode 100644 docs/en/img/pomodoro_init.png create mode 100644 docs/en/img/pomodoro_run.png create mode 100644 docs/en/img/presentations_scripts.png create mode 100644 docs/en/img/presentations_styles.png create mode 100644 docs/en/img/project_directory.png create mode 100644 docs/en/img/settings_advanced.png create mode 100644 docs/en/img/settings_display.png create mode 100644 docs/en/img/settings_editor.png create mode 100644 docs/en/img/settings_export.png create mode 100644 docs/en/img/settings_general.png create mode 100644 docs/en/img/settings_project.png create mode 100644 docs/en/img/settings_zettelkasten.png create mode 100644 docs/en/img/sorting_indicators.png create mode 100644 docs/en/img/table_active_cell.png create mode 100644 docs/en/img/table_with_edge_buttons.png create mode 100644 docs/en/img/tags_settings.png create mode 100644 docs/en/img/translations_list.png create mode 100644 docs/en/img/writing_targets.png create mode 100644 docs/en/img/writing_targets_settings.png create mode 100644 docs/en/img/zettlr_ide.png create mode 100644 docs/en/img/zettlr_notes.png create mode 100644 docs/en/img/zettlr_table.png create mode 100644 docs/en/img/zettlr_table_movement.png create mode 100644 docs/en/img/zettlr_zettelkasten.png create mode 100644 docs/en/img/zettlt_tex_file.png create mode 100644 docs/en/index.md create mode 100755 docs/en/install.md create mode 100755 docs/en/reference/markdown-basics.md create mode 100755 docs/en/reference/settings.md create mode 100755 docs/en/reference/shortcuts.md create mode 100755 docs/en/reference/spell-checking.md delete mode 100644 docs/img/.DS_Store create mode 100755 scripts/build.sh create mode 100755 scripts/serve.sh diff --git a/README.md b/README.md index c3593ce8..af45e1aa 100644 --- a/README.md +++ b/README.md @@ -18,11 +18,11 @@ As soon as we run a new build, your changes will automatically be included and a ## New Pages and Changes to the Structure -New pages in our documentation will require some structural adjustments, which you need to discuss beforehand. If you have an idea on how to structure the documentation, please discuss your proposal on our [forum](https:/7forum.zettlr.com). +New pages in our documentation will require some structural adjustments, which you need to discuss beforehand. If you have an idea on how to structure the documentation, please discuss your proposal on our [forum](https://forum.zettlr.com). ## The Structure -All source files reside in the `docs` directory. The images reside in the `img` directory within the `docs`-directory. The names of the files should speak for themselves. The `assets`-subdirectory holds additional files that are necessary for building the docs. +These docs are multi-language. Inside the `docs`-subdirectory, you'll find all languages inside ISO-coded directories. Inside these, you will find one `assets`-folder, which contains a symbolic link to the top-level assets's `app.css`-file. The rest of the files are independent and unique for each language. You can create a `resources` directory on the root level to store additional files that you may need, as the `.gitignore` file will not commit this directory. @@ -30,19 +30,32 @@ You can create a `resources` directory on the root level to store additional fil To locally test how your changes work out, you'll need to install [MkDocs](https://www.mkdocs.org/). MkDocs is a comprehensive library that allows for easy building of whole documentations. Please follow the instructions by the creators of MkDocs on how to set up the software on your computer. -If MkDocs is set up, inside your directory run: +Most of the default commands won't work with our setup, so please use the custom scripts: -```bash -$ mkdocs serve -``` +### serve.sh -to start up a local development server which will watch the files as you go. To build the page locally, run: +The `serve.sh`-script serves a specific language for testing. Simply run: ```bash -$ mkdocs build +$ ./scripts/serve.sh en ``` -Further commands and options are available at their [homepage](https://www.mkdocs.org/). +and replace "en" with an existing language code to spin up the development server. If you omit this, it will simply spin up the English language server. + +### build.sh + +The `build.sh`-scripts builds the full documentation. Simply run it. It will scan the `docs`-directory and run the corresponding `.yml`-configuration file located in the `config`-directory. + +## Create More Languages + +Want to add a language? Perfect, here's how you do it: + +1. Copy any of the configuration files in `./config`. Rename it to the corresponding ISO-code (e.g. `es` for Spanish, `fr` for French, and so on). +2. Create a new directory corresponding to the same ISO-code in `./docs`. +3. Inside this directory, create an `assets`-subdirectory and create a symbolic link to the `./assets/app.css`-CSS file. This is important so that changes to the master file are propagated to all languages, keeping it DRY. +4. Head to the `./assets/index.html`-file and add your language to the bottom (simply copy one of the existing list items, the changes necessary should be self-explanatory). +5. Add your documentation and adapt the `./config/.yml`-configuration file as appropriate. +6. Commit via PR. ## License diff --git a/docs/assets/app.css b/assets/app.css similarity index 96% rename from docs/assets/app.css rename to assets/app.css index 86c42b33..d8ea1f82 100644 --- a/docs/assets/app.css +++ b/assets/app.css @@ -3,7 +3,7 @@ /* * General branding: Let's use the Zettlr green instead of the default blue */ -section.wy-nav-content-wrap a { color: rgb(28, 178, 126); } +section.wy-nav-content-wrap a { color: black;}/*rgb(28, 178, 126); }*/ nav.wy-nav-top a, nav.my-nav-top a:active { color: white; } .wy-side-nav-search a, .wy-side-nav-search a:visited { color: white; } diff --git a/assets/index.html b/assets/index.html new file mode 100644 index 00000000..1057e02b --- /dev/null +++ b/assets/index.html @@ -0,0 +1,66 @@ + + + + + + + Zettlr Docs + + + +
+

Zettlr Docs

+

+ Please select your language. +

+

+

+

+
+ + diff --git a/config/de.yml b/config/de.yml new file mode 100644 index 00000000..2555f767 --- /dev/null +++ b/config/de.yml @@ -0,0 +1,62 @@ +site_name: Zettlr Docs +site_url: https://docs.zettlr.com/de +repo_url: https://github.com/Zettlr/zettlr-docs +site_description: >- + Die Dokumentation für den Markdown-Editor Zettlr enthält alle Informationen + zum erfolgreichen Schreiben. +site_author: Hendrik Erz +copyright: "© 2017-2019 by Zettlr" +docs_dir: ../docs/de +site_dir: ../build/de +edit_uri: edit/master/docs/de +extra_css: + - assets/app.css +nav: + - Willkommen: index.md + - Installation: install.md + - Schnellstart: 5-minutes.md + - Anleitungen: + - Zettlr als Notizapp: guides/guide-notes.md + - Zettlr als Zettelkasten: guides/guide-zettelkasten.md + - Zettlr als IDE: guides/guide-ide.md + - Core: + - Editor: core/editor.md + - Dateiliste: core/file-list.md + - Suchen: core/search.md + - Exportieren: core/export.md + - Tabelleneditor: core/tables.md + - Virtuelle Verzeichnisse: core/virtual-directories.md + - Custom CSS: core/custom-css.md + - Lokalisation: core/localisation.md + - Seitenleiste: core/attachments.md + - Wissenschaftliche Werkzeuge: + - Zitationen: academic/citations.md + - Projekte: academic/projects.md + - Präsentationen: academic/presentations.md + - Pomodoro-Timer: academic/pomodoro.md + - Lesbarkeitsmodus: academic/readability.md + - Zettelkastenmethodologie: academic/zkn-method.md + - Eigene Vorlagen: academic/custom-templates.md + - Referenzen: + - Tastaturkürzel: reference/shortcuts.md + - Markdown-Grundlagen: reference/markdown-basics.md + - Einstellungen: reference/settings.md + - Rechtschreibprüfung: reference/spell-checking.md + - Mach mit!: get-involved.md + - FAQ: faq.md +theme: + name: readthedocs + custom_dir: ../theme_override + highlightjs: True + prev_next_buttons_location: both + hljs_languages: + - javascript + - css + - yaml + - tex +markdown_extensions: + - toc: + permalink: True +plugins: + - search: + lang: de diff --git a/mkdocs.yml b/config/en.yml similarity index 84% rename from mkdocs.yml rename to config/en.yml index 58507ad0..ebe6621a 100644 --- a/mkdocs.yml +++ b/config/en.yml @@ -1,11 +1,14 @@ site_name: Zettlr Docs -site_url: https://docs.zettlr.com +site_url: https://docs.zettlr.com/en repo_url: https://github.com/Zettlr/zettlr-docs -site_description: Our comprehensive documentation provides you with everything you need to know about how to make the most of Zettlr. +site_description: >- + Our comprehensive documentation provides you with everything you need to + know about how to make the most of Zettlr. site_author: Hendrik Erz copyright: "© 2017-2019 by Zettlr" -docs_dir: docs -site_dir: build +docs_dir: ../docs/en +site_dir: ../build/en +edit_uri: edit/master/docs/en extra_css: - assets/app.css nav: @@ -43,7 +46,7 @@ nav: - FAQ: faq.md theme: name: readthedocs - custom_dir: theme_override + custom_dir: ../theme_override highlightjs: True prev_next_buttons_location: both hljs_languages: diff --git a/docs/5-minutes.md b/docs/de/5-minutes.md similarity index 100% rename from docs/5-minutes.md rename to docs/de/5-minutes.md diff --git a/docs/academic/citations.md b/docs/de/academic/citations.md similarity index 100% rename from docs/academic/citations.md rename to docs/de/academic/citations.md diff --git a/docs/academic/custom-templates.md b/docs/de/academic/custom-templates.md similarity index 100% rename from docs/academic/custom-templates.md rename to docs/de/academic/custom-templates.md diff --git a/docs/academic/pomodoro.md b/docs/de/academic/pomodoro.md similarity index 100% rename from docs/academic/pomodoro.md rename to docs/de/academic/pomodoro.md diff --git a/docs/academic/presentations.md b/docs/de/academic/presentations.md similarity index 100% rename from docs/academic/presentations.md rename to docs/de/academic/presentations.md diff --git a/docs/academic/projects.md b/docs/de/academic/projects.md similarity index 100% rename from docs/academic/projects.md rename to docs/de/academic/projects.md diff --git a/docs/academic/readability.md b/docs/de/academic/readability.md similarity index 100% rename from docs/academic/readability.md rename to docs/de/academic/readability.md diff --git a/docs/academic/zkn-method.md b/docs/de/academic/zkn-method.md similarity index 100% rename from docs/academic/zkn-method.md rename to docs/de/academic/zkn-method.md diff --git a/docs/de/assets/app.css b/docs/de/assets/app.css new file mode 120000 index 00000000..62ed8c5c --- /dev/null +++ b/docs/de/assets/app.css @@ -0,0 +1 @@ +../../../assets/app.css \ No newline at end of file diff --git a/docs/core/attachments.md b/docs/de/core/attachments.md similarity index 100% rename from docs/core/attachments.md rename to docs/de/core/attachments.md diff --git a/docs/core/custom-css.md b/docs/de/core/custom-css.md similarity index 100% rename from docs/core/custom-css.md rename to docs/de/core/custom-css.md diff --git a/docs/core/editor.md b/docs/de/core/editor.md similarity index 100% rename from docs/core/editor.md rename to docs/de/core/editor.md diff --git a/docs/core/export.md b/docs/de/core/export.md similarity index 100% rename from docs/core/export.md rename to docs/de/core/export.md diff --git a/docs/core/file-list.md b/docs/de/core/file-list.md similarity index 100% rename from docs/core/file-list.md rename to docs/de/core/file-list.md diff --git a/docs/core/localisation.md b/docs/de/core/localisation.md similarity index 100% rename from docs/core/localisation.md rename to docs/de/core/localisation.md diff --git a/docs/core/search.md b/docs/de/core/search.md similarity index 100% rename from docs/core/search.md rename to docs/de/core/search.md diff --git a/docs/core/tables.md b/docs/de/core/tables.md similarity index 100% rename from docs/core/tables.md rename to docs/de/core/tables.md diff --git a/docs/core/virtual-directories.md b/docs/de/core/virtual-directories.md similarity index 100% rename from docs/core/virtual-directories.md rename to docs/de/core/virtual-directories.md diff --git a/docs/faq.md b/docs/de/faq.md similarity index 100% rename from docs/faq.md rename to docs/de/faq.md diff --git a/docs/get-involved.md b/docs/de/get-involved.md similarity index 100% rename from docs/get-involved.md rename to docs/de/get-involved.md diff --git a/docs/guides/guide-ide.md b/docs/de/guides/guide-ide.md similarity index 100% rename from docs/guides/guide-ide.md rename to docs/de/guides/guide-ide.md diff --git a/docs/guides/guide-notes.md b/docs/de/guides/guide-notes.md similarity index 100% rename from docs/guides/guide-notes.md rename to docs/de/guides/guide-notes.md diff --git a/docs/guides/guide-zettelkasten.md b/docs/de/guides/guide-zettelkasten.md similarity index 100% rename from docs/guides/guide-zettelkasten.md rename to docs/de/guides/guide-zettelkasten.md diff --git a/docs/img/attachment-pane-references.png b/docs/de/img/attachment-pane-references.png similarity index 100% rename from docs/img/attachment-pane-references.png rename to docs/de/img/attachment-pane-references.png diff --git a/docs/img/attachment_sidebar.png b/docs/de/img/attachment_sidebar.png similarity index 100% rename from docs/img/attachment_sidebar.png rename to docs/de/img/attachment_sidebar.png diff --git a/docs/img/attachment_sidebar_images.png b/docs/de/img/attachment_sidebar_images.png similarity index 100% rename from docs/img/attachment_sidebar_images.png rename to docs/de/img/attachment_sidebar_images.png diff --git a/docs/img/back.png b/docs/de/img/back.png similarity index 100% rename from docs/img/back.png rename to docs/de/img/back.png diff --git a/docs/img/create.png b/docs/de/img/create.png similarity index 100% rename from docs/img/create.png rename to docs/de/img/create.png diff --git a/docs/img/create_tex_file.png b/docs/de/img/create_tex_file.png similarity index 100% rename from docs/img/create_tex_file.png rename to docs/de/img/create_tex_file.png diff --git a/docs/img/custom_css_pilcrow.png b/docs/de/img/custom_css_pilcrow.png similarity index 100% rename from docs/img/custom_css_pilcrow.png rename to docs/de/img/custom_css_pilcrow.png diff --git a/docs/img/custom_css_unsplash.png b/docs/de/img/custom_css_unsplash.png similarity index 100% rename from docs/img/custom_css_unsplash.png rename to docs/de/img/custom_css_unsplash.png diff --git a/docs/img/export-to-csl-json.png b/docs/de/img/export-to-csl-json.png similarity index 100% rename from docs/img/export-to-csl-json.png rename to docs/de/img/export-to-csl-json.png diff --git a/docs/img/export.png b/docs/de/img/export.png similarity index 100% rename from docs/img/export.png rename to docs/de/img/export.png diff --git a/docs/img/file_meta.png b/docs/de/img/file_meta.png similarity index 100% rename from docs/img/file_meta.png rename to docs/de/img/file_meta.png diff --git a/docs/img/long_markdown_table.png b/docs/de/img/long_markdown_table.png similarity index 100% rename from docs/img/long_markdown_table.png rename to docs/de/img/long_markdown_table.png diff --git a/docs/img/markdown.png b/docs/de/img/markdown.png similarity index 100% rename from docs/img/markdown.png rename to docs/de/img/markdown.png diff --git a/docs/img/open.png b/docs/de/img/open.png similarity index 100% rename from docs/img/open.png rename to docs/de/img/open.png diff --git a/docs/img/pdf_settings_font.png b/docs/de/img/pdf_settings_font.png similarity index 100% rename from docs/img/pdf_settings_font.png rename to docs/de/img/pdf_settings_font.png diff --git a/docs/img/pomodoro_init.png b/docs/de/img/pomodoro_init.png similarity index 100% rename from docs/img/pomodoro_init.png rename to docs/de/img/pomodoro_init.png diff --git a/docs/img/pomodoro_run.png b/docs/de/img/pomodoro_run.png similarity index 100% rename from docs/img/pomodoro_run.png rename to docs/de/img/pomodoro_run.png diff --git a/docs/img/presentations_scripts.png b/docs/de/img/presentations_scripts.png similarity index 100% rename from docs/img/presentations_scripts.png rename to docs/de/img/presentations_scripts.png diff --git a/docs/img/presentations_styles.png b/docs/de/img/presentations_styles.png similarity index 100% rename from docs/img/presentations_styles.png rename to docs/de/img/presentations_styles.png diff --git a/docs/img/project_directory.png b/docs/de/img/project_directory.png similarity index 100% rename from docs/img/project_directory.png rename to docs/de/img/project_directory.png diff --git a/docs/img/settings_advanced.png b/docs/de/img/settings_advanced.png similarity index 100% rename from docs/img/settings_advanced.png rename to docs/de/img/settings_advanced.png diff --git a/docs/img/settings_display.png b/docs/de/img/settings_display.png similarity index 100% rename from docs/img/settings_display.png rename to docs/de/img/settings_display.png diff --git a/docs/img/settings_editor.png b/docs/de/img/settings_editor.png similarity index 100% rename from docs/img/settings_editor.png rename to docs/de/img/settings_editor.png diff --git a/docs/img/settings_export.png b/docs/de/img/settings_export.png similarity index 100% rename from docs/img/settings_export.png rename to docs/de/img/settings_export.png diff --git a/docs/img/settings_general.png b/docs/de/img/settings_general.png similarity index 100% rename from docs/img/settings_general.png rename to docs/de/img/settings_general.png diff --git a/docs/img/settings_project.png b/docs/de/img/settings_project.png similarity index 100% rename from docs/img/settings_project.png rename to docs/de/img/settings_project.png diff --git a/docs/img/settings_zettelkasten.png b/docs/de/img/settings_zettelkasten.png similarity index 100% rename from docs/img/settings_zettelkasten.png rename to docs/de/img/settings_zettelkasten.png diff --git a/docs/img/sorting_indicators.png b/docs/de/img/sorting_indicators.png similarity index 100% rename from docs/img/sorting_indicators.png rename to docs/de/img/sorting_indicators.png diff --git a/docs/img/table_active_cell.png b/docs/de/img/table_active_cell.png similarity index 100% rename from docs/img/table_active_cell.png rename to docs/de/img/table_active_cell.png diff --git a/docs/img/table_with_edge_buttons.png b/docs/de/img/table_with_edge_buttons.png similarity index 100% rename from docs/img/table_with_edge_buttons.png rename to docs/de/img/table_with_edge_buttons.png diff --git a/docs/img/tags_settings.png b/docs/de/img/tags_settings.png similarity index 100% rename from docs/img/tags_settings.png rename to docs/de/img/tags_settings.png diff --git a/docs/img/translations_list.png b/docs/de/img/translations_list.png similarity index 100% rename from docs/img/translations_list.png rename to docs/de/img/translations_list.png diff --git a/docs/img/writing_targets.png b/docs/de/img/writing_targets.png similarity index 100% rename from docs/img/writing_targets.png rename to docs/de/img/writing_targets.png diff --git a/docs/img/writing_targets_settings.png b/docs/de/img/writing_targets_settings.png similarity index 100% rename from docs/img/writing_targets_settings.png rename to docs/de/img/writing_targets_settings.png diff --git a/docs/img/zettlr_ide.png b/docs/de/img/zettlr_ide.png similarity index 100% rename from docs/img/zettlr_ide.png rename to docs/de/img/zettlr_ide.png diff --git a/docs/img/zettlr_notes.png b/docs/de/img/zettlr_notes.png similarity index 100% rename from docs/img/zettlr_notes.png rename to docs/de/img/zettlr_notes.png diff --git a/docs/img/zettlr_table.png b/docs/de/img/zettlr_table.png similarity index 100% rename from docs/img/zettlr_table.png rename to docs/de/img/zettlr_table.png diff --git a/docs/img/zettlr_table_movement.png b/docs/de/img/zettlr_table_movement.png similarity index 100% rename from docs/img/zettlr_table_movement.png rename to docs/de/img/zettlr_table_movement.png diff --git a/docs/img/zettlr_zettelkasten.png b/docs/de/img/zettlr_zettelkasten.png similarity index 100% rename from docs/img/zettlr_zettelkasten.png rename to docs/de/img/zettlr_zettelkasten.png diff --git a/docs/img/zettlt_tex_file.png b/docs/de/img/zettlt_tex_file.png similarity index 100% rename from docs/img/zettlt_tex_file.png rename to docs/de/img/zettlt_tex_file.png diff --git a/docs/index.md b/docs/de/index.md similarity index 100% rename from docs/index.md rename to docs/de/index.md diff --git a/docs/install.md b/docs/de/install.md similarity index 100% rename from docs/install.md rename to docs/de/install.md diff --git a/docs/reference/markdown-basics.md b/docs/de/reference/markdown-basics.md similarity index 100% rename from docs/reference/markdown-basics.md rename to docs/de/reference/markdown-basics.md diff --git a/docs/reference/settings.md b/docs/de/reference/settings.md similarity index 100% rename from docs/reference/settings.md rename to docs/de/reference/settings.md diff --git a/docs/reference/shortcuts.md b/docs/de/reference/shortcuts.md similarity index 100% rename from docs/reference/shortcuts.md rename to docs/de/reference/shortcuts.md diff --git a/docs/reference/spell-checking.md b/docs/de/reference/spell-checking.md similarity index 100% rename from docs/reference/spell-checking.md rename to docs/de/reference/spell-checking.md diff --git a/docs/en/5-minutes.md b/docs/en/5-minutes.md new file mode 100755 index 00000000..8e6987e9 --- /dev/null +++ b/docs/en/5-minutes.md @@ -0,0 +1,69 @@ +# Zettlr in 5 Minutes + +Okay, you have downloaded and installed the app, got a clock set and are ready to roll? Then hit that countdown button and let's go! + +## 1. Open directories and files + +To open directories or files, simply drag them anywhere over the app's window. They will be opened automatically. You can also hit `Cmd/Ctrl+O` to open the directory select dialog, if that's faster for where you're going. + +![open.png](img/open.png) + +## 2. Create files and directories + +After opening a directory, you need a file. Hit `Cmd/Ctrl+N` to create a new file. Type a file name, hit `Return` and select the editor. Need another directory? `Cmd/Ctrl+Shift+N` will do the job. + +![create.png](img/create.png) + +> You can not only add Markdown files! If you do not provide an extension, Zettlr will add the extension `.md` for you. But you can also create `.txt`-files and `.tex`-files, you just need to provide that file extension! + +## 3. Write! + +Writing is up to you, but here's the most important keystrokes to remember: + +- `Cmd/Ctrl+I`: Make text \__italic_\_. Works just like in Word. +- `Cmd/Ctrl+B`: Make text \*\***bold**\*\*. Also works just like in Word. +- `Cmd+Alt+R` (macOS) `Ctrl+Alt+F` (Windows/Linux): Create a footnote. +- `Alt/Ctrl+Click` (on a footnote reference): Edit a footnote. Hit `Shift+Enter` to finish editing. +- `Cmd/Ctrl+K`: Insert a link. (`Alt/Ctrl+Click` it to open the link.) +- `Cmd/Ctrl+J`: Enter the distraction-free mode. +- `Cmd/Ctrl+Alt+L`: Toggle the theme between light and dark mode. + +![markdown.png](img/markdown.png) + +Things without keystrokes, but also important: + +- Use `#`-signs to create headings. The number of `#`-symbols equals the level of the heading. Maximum is 6. +- Use `>`-signs to create blockquotes. You can also nest them using multiple greater-than-signs (e.g. `> >`). +- Use `#`-signs _not_ followed by a space to create tags. You can use these tags for searching and navigating. + +## 4. What else? + +If you use the thin sidebar mode (the default), you will see either the file list or the directory tree. Move the mouse to the top-left corner of the file list and click the arrow to show the directory tree. To toggle between file list and directory tree, you can also hit `Cmd/Ctrl+!`. Choose the extended sidebar mode in the preferences to have both the file list and the directory tree visible at once. + +![back.png](img/back.png) + +Zettlr is strictly context-based. Unless otherwise specified, new files and directories will be created inside the currently selected directory. File-based operations (renaming or deleting) will by default target the current file. Use the context menu by right-clicking any file or directory to select specific files/directories. + +Three simple rules of thumb: + +1. The `Alt`(ernative) key triggers alternative actions on the same element. +2. The `Shift` modifier key _shifts_ the target of an action to another element (mostly the directory instead of the file). +3. All crucial actions are located in the toolbar. Left are general actions, middle are file-based actions, and to the right are other actions. + +## 5. Nice, I've finished writing. How do I share it? + +Three easy steps: + +1. Make sure Pandoc and LaTeX (only necessary for PDF) are installed. +2. Click the share button in the toolbar (or hit `Cmd/Ctrl+E`) and select the target format. The aperture reveals the presentations (they are made using reveal.js — get the pun?) +3. On export, Zettlr opens the exported file automatically in your preferred app. In there, hit `Cmd/Ctrl+Shift+S` (should work in most apps) to save it where ever you want. + +![export.png](img/export.png) + +## 6. Okay, the 5 mins are over, something else? + +Nope, you're good to go. If you want to dive deeper, be sure to check out our guides: + +- [Zettlr as a note-taking app](guides/guide-notes.md) +- [Zettlr as a Zettelkasten](guides/guide-zettelkasten.md) +- [Zettlr as an IDE](guides/guide-ide.md) diff --git a/docs/en/academic/citations.md b/docs/en/academic/citations.md new file mode 100755 index 00000000..27bb161b --- /dev/null +++ b/docs/en/academic/citations.md @@ -0,0 +1,95 @@ +# Citing with Zettlr + +Starting with version `1.0.0`, it's possible to cite sources directly using Zettlr. This feature makes writing academic papers a lot easier than in the past, because you don't need to circumvent the Zettlr export function to actually cite academic papers anymore! + +Citing in Zettlr is done using `citeproc-js`, a library that works exactly like, for instance, pandoc's citeproc-engine, or Zotero. So what you will be seeing in Zettlr matches what Zotero's Word or LibreOffice plugins generate. Zettlr's citation engine is composed of three components: A CSL JSON or BibTex library which contains all items that can be cited, optionally a CSL Stylesheet which can alter Zettlr's default citation style (which is the [American Psychological Association's 6th edition](https://www.apastyle.org/manual/index), short: APA), and a preview engine. This guide will help you enable citations and produce beautifully looking files (not just PDF!) that contain correct and consistent citations. + +> Beginning from `1.3.0`, you can also use BibTex libraries to cite. + +## Enabling Citations in Zettlr + +There are two different engines that belong to the realm of citing: the previews (citations can be previewed just as images or links) and the actual process of generating citations (which happens only on export). Both of these functions are triggered by selecting a citation library that contains references. Without such a library, Zettlr will still "preview" citations (so that you can see what will trigger pandoc's citeproc), but Zettlr won't replace the citation's contents with a generated citation. Also, if you do not specify such a library, Zettlr will _not_ run Pandoc with its citeproc-engine, and therefore will not parse the citations. + +So the first step is to create such a file. Zotero is the recommended application for managing your library, so this tutorial will assume you use Zotero. If you use another program, please check out how to export from your software to the CSL JSON format. + +> If you use Mendeley, Citavi, or any other references management software that does not export to CSL JSON, you can simply use BibTex-files. They will work the same way as CSL JSON files. + +### Step 1: Install BetterBibTex + +The first step is to install [the BetterBibTex-plugin for Zotero](https://github.com/retorquere/zotero-better-bibtex/releases/latest). This plugin's main benefit is that it keeps your citation IDs unique throughout your entire library. Each citation item has its own unique ID. This is necessary so that when you, for instance, realise that the publication date has been saved wrong, you can easily change it in Zotero and afterwards citeproc will use the corrected information. If you do not use BetterBibTex, it may always happen that an ID is issued multiple times, which would either generate errors (the good way, because you know there's something wrong) or simply use the first item that matches this ID (the bad way, because this way you'd have to be lucky to spot the wrong citation after export). + +After you've installed BetterBibTex, you may want to play around a little bit with the settings (for instance in how the IDs are generated). + +> **Tip**: BetterBibTex automatically generates unique keys using an algorithm that you can customise. For most part, it makes use of the established [JabRef Patterns](http://help.jabref.org/en/BibtexKeyPatterns) but extends them significantly. It will even make sure that each entry is unique by optionally adding a suffix to puplications which yield the same keys (e.g. you'll have something like `Harvey2005a`, `Harvey2005b`, `Harvey2005c`, and so forth). You can find [all abilities of BetterBibTex in the plugin's extensive documentation](https://retorque.re/zotero-better-bibtex/citation-keys/). + +### Step 2: Export your library + +The next step is to actually export your library. Zotero's task is to manage your references, but to cite them is another task, which is done by citeproc. And citeproc needs a separate file for that. + +To export such a library that both Zettlr and pandoc's citeproc can use, first select the collection you want to export in the left sidebar. To always have all your items at your disposal and to prevent having to export multiple different libraries, you can select your entire library. (_As a measure: We've run tests with a library containing about 700 items, and we have not experienced any performance issues._) + +![Export your Library as Better CSL JSON](../img/export-to-csl-json.png) + +Next, click on `File` and select `Export library …`. As the format, select `Better CSL JSON` (if you opted against installing BetterBibTex you may choose `CSL JSON`). If you check the checkbox labeled "Keep updated", BetterBibTex will make sure that every change in Zotero will automatically be exported to the file, keeping it in sync with Zotero (and, therefore, transmit your changes automatically to Zettlr, which in turn will always cite correctly). + +If you ticked the checkbox, you can check the status of the library file by opening the Zotero Preferences, selecting the `BetterBibTex`-tab, and selecting `Automatic Export`, which allows you to further finetune what is exported, and when. + +### Step 3: Open your library in Zettlr + +Now it is time to import your library to Zettlr. To do so, simply open Zettlr's preferences, go to the `Export`-tab and click the small folder-icon right to the `Citation Database`-input field. A dialog will appear that lets you navigate to your database file. Select it, save the preferences and Zettlr will automatically load the database. Now you are ready to cite! + +![Point Zettlr to your database file](../img/settings_export.png) + +## Citing in Zettlr + +Citing in Zettlr is very easy. Zettlr supports pandoc's citeproc-syntax for writing citations, so you'll have two options on how to write citations. First, you can simply throw a single identifier somewhere in your text to simply render a citation for this key. It should look like this: `@Harvey2005a`. All citation keys begin with an `@` followed by the citation key. + +> Zettlr has an autocomplete-feature that will prompt you with a selection of all available citation keys as soon as you type an `@`-character. This is a first check if you're using the correct ID: If Zettlr doesn't offer you anything, the ID has probably not been found in the library file. + +But normally you'll want to be somewhat more specific, add a certain page range or something like that to your citation. That is what the more extended square-bracket citation is for. To cite in this way simply use square brackets. A citation with a so-called prefix and a page-range would look like this: + +`[See @Harvey2005a, 45-51]` + +To cite multiple authors, simply divide the blocks with semicolons: + +`[See @Harvey2005a, 45-51; also @Ciepley2007, 8-9]` + +For more information on how to use citations in line with pandoc's citeproc engine, [please refer to the guide](http://pandoc.org/demo/example19/Extension-citations.html). + +> **Please note** that Zettlr's citeproc-engine is **only for preview purposes**. For simplicity reasons, Zettlr does not perfectly parse all citations and will therefore lack some precision. You can be sure that pandoc's citeproc will do the job correctly on export. Therefore, the preview citations are **only to check that your citations are detected correctly so you won't have missing citations on export**. + +## Checking the references + +After you're done citing and want to check that you've cited everything you planned to, you can open the `Attachment Sidebar` (Shortcut: `Ctrl/Cmd+3`). Beneath all files that are in your currently selected directory, Zettlr will display a list of all references it has found in your current file. If something's missing from there, it's probably not been cited in your file. + +![References in the Attachment Pane](../img/attachment-pane-references.png) + +## Changing the citation style + +Internally, Zettlr will always only use the APA-style to generate citations. Therefore, your previewed citations will always be "in-text," and never in footnote-style. This is meant as a convenience for you to simply see that everything works out. + +But of course you can also use different citation styles, depending on either the journal requirements for which you are writing, or your personal preferences. To change the style in which pandoc's citeproc will render your citations, you'll need to download the respective CSL-file. A very good starting point is the [Zotero style repository](https://www.zotero.org/styles). There you can search for specific citation styles, preview them and download them. + +You can point Zettlr to such CSL-files at two obvious points. First in the general preferences. In the `Export`-tab, beneath the field for your citation database file, you can select your preferred CSL-style which will then be used for all single-page exports that you export using the toolbar button. + +But obviously, for projects you may want to use a different CSL-style. Therefore, if you open any project's preferences, you can select a CSL-file as well. The project will then use this on export. + +## Formatting the List of References + +Of course, as soon as you cite reference works in your files, you'll want the references to be formatted neatly. If you export to Word or LibreOffice, you can change the respective formatting styles as you edit your file before sending it out. But as soon as you export to PDF, this won't be possible. And as `pandoc-citeproc` simply glues all your references to the end of the document with no formatting whatsoever, you'll need to perform a little trick to make the references list look nicely. + +LaTeX uses lengths to determine the overall measurements of the exported PDF. These lengths are normally set globally, but can be transformed during the course of the source file. One of these lengths is `parindent`, which controls the hanging indent of all paragraphs. There are additional lengths for when paragraphs follow a heading, for example, but we won't be concerned with these for now. + +The `parindent`-variable can be set using Zettlr's PDF-options, but it will only be set globally for all paragraphs. As the references are also formatted using general paragraph styles, they will be indented in the same manner as all other paragraphs. But there's a small trick you can use to make the bibliography look nice: simply overwrite the paragraph lengths _after_ your document, that is: after the heading `## References` (or however you call it in your file). + +Simply re-set them to what looks nicely to you. The following code snippet gives you an example: + +```latex +\setlength{\parindent}{-1cm} % Negative hanging indent +\setlength{\leftskip}{0.5cm} % Overall indentation +\setlength{\parskip}{0.1cm} % Spacing between paragraphs +``` + +The above example would render the bibliography with a negative indentation of minus one centimetre. Additionally it'll apply an overall indentation of half a centimetre (relative to the page margins, so if your left page margin is set to 3 centimetres, the bibliography paragraphs will be offset 3.5 centimetres as opposed to the normal paragraphs, which are offset only 3 centimetres). The last value (`parskip`) controls the spacing _between_ paragraphs, so each one will be 10 millimetres away from each other. + +Simply start from there, maybe search for more lengths to tweak and adjust these lengths to your liking. diff --git a/docs/en/academic/custom-templates.md b/docs/en/academic/custom-templates.md new file mode 100644 index 00000000..d11fee30 --- /dev/null +++ b/docs/en/academic/custom-templates.md @@ -0,0 +1,113 @@ +# Custom Templates + +While [Custom CSS](../core/custom-css.md) is a great way to make Zettlr your own through appearance, it doesn't make your papers truly yours. Once you are done with writing, aesthetics matter just as much as the content. Your ideas are worth a lot on their own, but without great design and a typography that invites you to read, your ideas will suffer. + +You want your own font, a good line spacing and maybe even some colours. While the [PDF Preferences](../reference/settings.md) allow you to customise some general settings both on a per-project basis as well as for single file exports, you can't really make use of all the features that LaTeX typesetting gives you. And, oh boy, [there are so good examples](https://tex.stackexchange.com/questions/1319/showcase-of-beautiful-typography-done-in-tex-friends). + +Luckily, one of the core principles of Zettlr's philosophy is to not only give you the most amount of freedom to use tools like Pandoc and LaTeX to your benefit, it also makes it work _well_ for you. This page is meant to give you a headstart of using custom LaTeX templates for your work, so that both your writing and the final product is fit for showcasing! + +## Preconsiderations + +Before getting started with writing your own, custom LaTeX templates, we should spend some words on what will be happening on export. The Zettlr exporting engine is a mighty piece of software that performs a variety of tasks before handing off your documents to Pandoc for the final steps. It is of some importance to know what Zettlr will do to your documents to ensure consistent output and prevent problems and hiccups, especially once you perform more advanced templating. This chapter is dedicated to explaining all steps that Zettlr will perform on your projects and file exports before handing off to Pandoc (which in turn hands off the file to LaTeX). + +### 1. Concatenate All Input Files (Only Applies to Projects) + +If you are exporting a project, Zettlr will first perform a simple task: It will concatenate all your files in the way they are displayed to you in the file list and write them to a single temporary file. In order to do so, it will read in the project directory the same way the file list will do (thereby preserving the order), and read in the files. During this step, **two operations will be performed on the Markdown source**: + +1. All image paths will be converted to absolute images. This is for security reasons, as LaTeX will fail to export if the image paths are not absolute (as the CWD of LaTeX will not be the one where your Markdown file resides). This way, you can use relative paths everywhere without having to worry about what LaTeX will do to them. +2. Make all footnotes unique. Each of your chapters will start with footnote number 1. Therefore, in most cases you would have duplicate footnotes which might fail to export or, even worse, one of the duplicates will be used, while the others will be omitted. Zettlr makes footnotes unique by prepending the file's internal hash. So out of a `[^1]`, Zettlr will create for instance `[^1934976181]`. This way every footnote will be unique. + +Afterwards, it will save the resulting file to the temporary directory and start up the exporter, which takes us to step 2. + +### 2. Read in the Source File + +The obvious thing to do for Zettlr is to read in your source file. It's either the file you want to export quickly using the `Share`-feature, or the generated, concatenated file from your project (see step 1). While reading the file in, it will make all image paths absolute (it won't happen if you're exporting a project, as the image paths are already absolute from step 1). + +Next, it will replace all tags, if you've checked the corresponding option in the preferences. In this step, it will also treat your Zettelkasten links, if applicable. It will either remove the link formatting characters (`[[` and `]]` by default) or completely remove everything. If you've turned this feature off, it will leave the links untouched. Additionally, if you've specified the respective option, it will strip all IDs. + +> This is the reason why the "Strip IDs" feature is off by default: It would, due to the nature of the default IDs to consist only of numbers, also make some types of web links unusable. + +After the file has been prepared, it will be saved to a temporary location. + +### 3. Prepare the Template + +After the file is ready, Zettlr will read in the template and write it to a temporary file. In this step, a number of variables within the template will be replaced. These are as follow: + +- `$PAGE_NUMBERING$`: The pagenumbering that you've chosen in the PDF preferences, e.g. Arabic Numbers. +- `$PAPER_TYPE$`: The paper that you've chosen, e.g. `a4paper`. +- `$TOP_MARGIN$`: The top pagemargin that you've provided (e.g. 3cm). +- `$RIGHT_MARGIN$`: The right page margin that you've provided (e.g. 3cm). +- `$BOTTOM_MARGIN$`: The bottom page margin that you've provided (e.g. 3cm). +- `$LEFT_MARGIN$`: The left page margin that you've provided (e.g. 3cm). +- `$MAIN_FONT$`: The main font (for most text) that you've provided (e.g. Times New Roman) +- `$SANS_FONT$`: The secondary font (mostly for headings) that you've provided (e.g. Arial) +- `$LINE_SPACING$`: The line spacing, provided by you (e.g. 150 %). +- `$FONT_SIZE$`: The font size provided by you (e.g. 12pt). +- `$PDF_TITLE$`: The PDF title (either the filename or custom, if exporting a project). +- `$PDF_SUBJECT$`: The PDF subject. +- `$PDF_AUTHOR$`: The PDF author meta information. +- `$PDF_KEYWORDS$`: Keywords for the PDF file. +- `$TITLEPAGE$`: Either an empty string or `\\maketitle\n\\pagebreak\n`, if you're exporting a project with the titlepage option on. +- `\$GENERATE_TOC$`: Either an empty string or `\\setcounter{tocdepth}{}\n\\tableofcontents\n\\pagebreak\n`, if you're exporting a project with the option checked to generate a table of contents. `` will be replaced with the level (1 to 6). + +These variables will be replaced globally, meaning that if the variable `\$PDF_AUTHOR$` is found multiple times in the template, it will be replaced each time. + +### 4. Prepare the PDF Export + +Now, with the files prepared, Zettlr will prepopulate the command variables that will be fed to the Pandoc engine. In this step, the prepared LaTeX template will be added to the command flags. If there is no custom template, Zettlr will use its default template, [which you can find here](https://github.com/Zettlr/Zettlr/blob/master/source/main/assets/export.tex). The default Zettlr template is an adaption of the Pandoc default template ([find it here](https://github.com/jgm/pandoc/blob/master/data/templates/default.latex)), with many of the additional sweeteners stripped for maximum compatibility. + +> Many of the commands in the default Pandoc template require additional LaTeX packages. The Zettlr PDF template strives for maximum compatibility, not for perfect PDFs, to not confuse users who only need the basics. + +### 5. Run the Command! + +Now, with all preconditions met, Zettlr will finally run the Pandoc command. It will pass the temporary input file as well as the temporary template file to it and let it do its job. In case you've decided to create a table of contents, Pandoc will be told to generate one. This means that, internally, Pandoc will run the XeLaTeX binary **twice**. This is because the XeLaTeX command needs to build a PDF so that it knows where the headings actually end up with all spacing applied, and then needs to build it again, only this time with the table of contents included. + +> It is of utmost importance to keep the ToC-flag in the Pandoc command (which you can edit on the advanced tab in the preferences), because if you remove it, the table of contents won't be included irrespective of the switch set in the Project settings! + +After the command has been run successfully, Zettlr will tell your operating system to open the file, so it'll be as if you've double-clicked on the final file. That means, it will be opened with your default PDF reader (or Word document editor, if you've chosen to export to Word, for example). If Pandoc exited with an error, this error will be shown to you using an extended error dialog from which you may also copy the error so that you can google it. + +> **Attention:** If LaTeX returns an error message, the full console output will be shown to you, which is---most of the time---both very verbose and also frustratingly vacuous. For example, if simply a LaTeX package is missing, it will output a long list of error messages where you need to spot the `File .sty is missing`. As a rule of thumb: If you neither use a custom template nor use any LaTeX stuff in your Markdown file, and _still_ experience an error, it indicates a problem with the default template. In this case please report it. In other cases, please consult LaTeX or Pandoc help forums first. + +## Getting Started with Templating + +Now it's time to get to building a template! You can either use an external editor to write your LaTeX template before pointing Zettlr to it. But of course it would be nice if you'd just be able to edit your LaTeX templates from within Zettlr, right? + +![Create TeX-Files by appending the appropriate extension](../img/create_tex_file.png) + +Oh boy, do we have good news. If you create a new file, but **provide as the file extension `.tex`**, Zettlr will not create a Markdown file but an actual LaTeX file! This file will be indicated with a small `TeX`-indicator in the file list (if file meta is turned on) and can be edited from within Zettlr. Hooray! + +![Zettlr with a TeX file open](../img/zettlt_tex_file.png) + +Zettlr will automatically detect if it's a LaTeX file and even switch the code highlighting from Markdown to LaTeX to help you write the file! + +## Necessary Contents + +Apart from the usual LaTeX stuff, there are a few things that need to be present in your files. Remember that the files will be passed down the line through a filter within Zettlr, then Citeproc (if applicable), and then Pandoc, before being passed to the LaTeX engine. Therefore, you can optionally leave out all Zettlr-specific variables altogether, but one variable needs to be present at all times: + +``` +$body$ +``` + +This variable will be replaced within Pandoc with the parsed contents of your Markdown file(s). If you leave it out, your contents will be pasted into oblivion, so make sure to never forget to place this variable where your content should end up! + +> This also means that while the default Zettlr template omits a lot of variables from the default Pandoc template, you are free to include all of them on your own! You can make use of the full array of Pandoc's variables, and of Zettlr's variables --- or just leave them out. This is where the templates become truly powerful. + +## Hacking Your Templates! + +Now let's get to the fun stuff. Over time, Zettlr has incorporated more and more options to finegrain your control over the exporting process. This means that you can actually do some fun stuff with Zettlr. For instance, you can completely circumvent all the nice things the exporting engine does to your files (except parsing the source file(s)) by simply changing the Pandoc command in your preferences to a fixed one. + +What you could also do is place Pandoc variables within your Zettlr variables (for instance setting the PDF author in your preferences to something including a Pandoc variable). Then, once Zettlr has run over your file, Pandoc will replace its own variable after the Zettlr variable has been replaced. + +And if you _really_ feel like hacking everything, have a second look at the Pandoc command. If you look closely, you can see that in front of the command there's `pandoc` written. Know what this means? You may have guessed it: The Pandoc command is not only just something that will be passed to Pandoc, but it's the **full console command that will be run**! What this means should now be obvious: You can run some custom scripts and logic before and after the actual Pandoc command runs! + +Let's assume you want to pass the temporary Markdown file to a custom script to perform even more actions, and afterwards move the file to some other place? Consider the following adaptation of the Pandoc command in the preferences: + +```shell +pandoc "$infile$" -f markdown $outflag$ $tpl$ $toc$ $tocdepth$ $citeproc$ $standalone$ --pdf-engine=xelatex -o "$outfile$" && cp "$outfile$" /Users/zettlr/Desktop/Final.pdf +``` + +This command would copy the final output file to the Desktop of the ficitional user "zettlr" and name it "Final.pdf" (assuming you run on macOS). Instead of using a simple shell command like `cp`, you could also pass whole scripts that would run afterwards. The sky really is the limit! + +## Final Thoughts + +Zettlr strives to give its users full command over what they can do with their files. What we've outlined on this page is only the start. We've not tried to go crazy ourselves, but you can really do stuff. How do you use Zettlr's possibilities to do weird things? Tell us on [Twitter](https://www.twitter.com/Zettlr), the [Forum](https://forum.zettlr.com/), or on [Reddit](https://www.reddit.com/r/Zettlr)! diff --git a/docs/en/academic/pomodoro.md b/docs/en/academic/pomodoro.md new file mode 100755 index 00000000..fd426545 --- /dev/null +++ b/docs/en/academic/pomodoro.md @@ -0,0 +1,39 @@ +# Pomodoro-Timer + +If you write a lot, the time may come that you need to organise your time better. The built-in Pomodoro-Timer can help you with this. + +Access the Pomodoro-Timer by clicking on the circle in the top right corner of the screen, inside the Toolbar. + +![Pomodoro Timer](../img/pomodoro_init.png) + +Don't know what a pomodoro timer is? Then head over to [the official website](https://francescocirillo.com/pages/pomodoro-technique)! + +## Using the Pomodoro-Timer + +Before you start the pomodoro timer, you can adapt some settings. + +The **red** number indicates the amount of minutes used to _work_. The default is 25 minutes. + +The **yellow** number indicates the duration of a _short_ break that will divide portions of work. After each work-phase there will be a short break. The default is 5 minutes. + +The **green** number tells Zettlr, how long a _long_ break should be. After every four tasks, there will be such a long break. The default duration is 20 minutes. + +Below, you can decide whether or not a sound should be played each time a phase has ended. The slider below the checkbox adjusts the volume. (_Attention_: This is not your system volume, so if your system's volume is only at 20 percent, even a volume of 100 percent inside Zettlr will only sound as loud as 20 percent!) + +Click on **Start** to begin the timer. Then, the circle will be filled with the color of the current phase (either red, yellow, or green). Once it is full, the next phase will begin. + +To **Stop** the timer or simply review the current **status** of the timer, click on the circle again. A small popup will tell you the remaining amount of time for the current phase, the type of the current phase and give you the option to stop. + +![Pomodoro Timer during Run](../img/pomodoro_run.png) + +The **cycle** of the pomodoro timer is as follows: + +1. Work +2. Short break +3. Work +4. Short break +5. Work +6. Short break +7. Work +8. Long break +9. _Repeat from step 1_ diff --git a/docs/en/academic/presentations.md b/docs/en/academic/presentations.md new file mode 100755 index 00000000..2565d660 --- /dev/null +++ b/docs/en/academic/presentations.md @@ -0,0 +1,125 @@ +# Presentations + +Since version `0.19.0`, Zettlr is able to export your Markdown files directly as presentation files using the [reveal.js](https://revealjs.com/#/)-framework. `reveal.js` is a lightweight solution for creating super compatible presentations using plain `HTML` and `JavaScript`. Therefore, these presentations can be shown on _all_ computers that run a browser — nowadays this means: they run on _every_ computer. + +For exporting Markdown files to `reveal.js`, you have to make sure Pandoc is installed on your computer. Head over to the [section on exporting](../core/export.md) to see how to install pandoc. + +If you first want to be impressed by an actual export from Zettlr into `reveal.js`, please have a look [at the demonstration presentation](https://zettlr.com/slides.revealjs.htm)! You can also read [the source file](https://www.zettlr.com/themes/zettlr/assets/slides.md) while following the instructions on this page. + +## Pre-considerations + +Of course, a Markdown document that should be compiled into a presentation has a slightly different structure than other Markdown documents. + +### Creating slides + +You can create new slides in two ways. First, each heading level 1 will begin a new slide and also act as the title of the slide. But in case the heading level 1 is too big for your taste, or you simply don't want a title on that slide, you can also delimit slides by using Markdown dividers (either `***` or `---`). + +Everything that follows the heading or the divider will end up being the content of the slides. You do not have to explicitly "end" the last slide with a divider. + +### Using Markdown elements + +Inside the slides, you can use all Markdown elements. They will be rendered as you would expect them. You can even use footnotes which will then be placed on their own, respective slide at the end! + +### Advanced Tools + +Of course, `reveal.js` presentations also have the same versatility as PowerPoint or Impress when it comes to controlling your presentation. For instance, you can use CSS-classes to tell the presentation that certain elements should be triggered before forwarding the presentation. These are called "fragments". Due to limitations in Pandoc's engine, you'll have to use plain HTML to achieve this. Consider, for instance, the HTML code from the demo presentation: + +```html +
    +
  • This item will fade in.
    • +
  • This will be highlighted blue.
    • +
  • All available transitions are documented [here](https://github.com/hakimel/reveal.js/#fragments).
    • +
+``` + +This will create a list with three items. All items are "fragments", which means that by pressing the shortcut for the next slide, the first will `fade-in`, as the class says. On the next press of the right arrow key, the second item will be highlighted in blue color. The third press of the right arrow key will highlight the last item red. And on the fourth press of the arrow key the next slide will be shown. + +### Presentation settings + +![presentations_scripts.png](../img/presentations_scripts.png) + +Of course, the presentation itself also has settings that you can make use of. These are simple JavaScript directives that you can manipulate by inserting a `