From ff41a1dc299e298016052f6c309c1f65c1030813 Mon Sep 17 00:00:00 2001 From: Serghei Iakovlev Date: Tue, 24 May 2022 17:52:16 +0200 Subject: Rewrite links to external resources --- exampleSite/content/about.md | 10 +++--- exampleSite/content/credits.md | 20 +++++------ exampleSite/content/documentation/index.md | 52 ++++++++++++++--------------- exampleSite/content/narratives/narrative.md | 2 +- exampleSite/content/poems/a-julia.md | 2 +- 5 files changed, 43 insertions(+), 43 deletions(-) diff --git a/exampleSite/content/about.md b/exampleSite/content/about.md index 5fa90ad..4a41f43 100644 --- a/exampleSite/content/about.md +++ b/exampleSite/content/about.md @@ -22,17 +22,17 @@ useful type of editions for editors and readers. An edition produced with Ed con pages whose rate of decay is substantially lower than database-driven systems. As an added bonus, these static pages require less bandwidth. Our hope is that our approach can help beginners and veterans deploy beautiful editions with less effort, and that it can help us teach a 'full stack' -[in one academic semester](https://github.com/susannalles/MinimalEditions/blob/master/README.md), +{{< link src="https://github.com/susannalles/MinimalEditions/blob/master/README.md" target="_blank" rel="noopener noreferrer" >}}in one academic semester{{< /link >}}, while allowing us to care for our projects at less cost, and perhaps, just perhaps, to generate high-quality editions on github.io in large quantities based on the -[git-lit](http://jonreeve.com/2015/09/introducing-git-lit/) model by Jonathan Reeve. We're coming +{{< link src="http://jonreeve.com/2015/09/introducing-git-lit/" target="_blank" rel="noopener noreferrer" >}}git-lit{{< /link >}} model by Jonathan Reeve. We're coming for you, Kindle! ## Sample Ed editions. -- [Our sample site](https://sergeyklay.github.io/gohugo-theme-ed/) is the first edition built with Ed. -- [Serghei Iakovlev's blog]: https://serghei.blog/?utm_source=ed&utm_campaign=docs&utm_medium=smm +- {{< link src="https://sergeyklay.github.io/gohugo-theme-ed/" target="_blank" rel="noopener noreferrer" >}}Our sample site{{< /link >}} is the first edition built with Ed. +- {{< link src="https://serghei.blog/?utm_source=ed&utm_campaign=docs&utm_medium=smm" target="_blank" rel="noopener noreferrer" >}}Serghei Iakovlev's blog{{< /link >}} ## Current Features @@ -46,7 +46,7 @@ for you, Kindle! - Metadata in Dublin Core and OpenGraph to play nice with Zotero, libraries and social media. - Automatic table of content generation - Simple search functionality -- Annotations via [hypothes.is](https://hypothes.is/) +- Annotations via {{< link src="https://hypothes.is/" target="_blank" rel="noopener noreferrer" >}}hypothes.is{{< /link >}} - Optional: Ability to generate well-formatted bibliographies and linked citations diff --git a/exampleSite/content/credits.md b/exampleSite/content/credits.md index 2e15157..00e1245 100644 --- a/exampleSite/content/credits.md +++ b/exampleSite/content/credits.md @@ -2,35 +2,35 @@ title: Credits --- -### [Serghei Iakovlev](https://www.linkedin.com/in/egrep/) | Software Engineer +### {{< link src="https://www.linkedin.com/in/egrep/" target="_blank" rel="noopener noreferrer" >}}Serghei Iakovlev{{< /link >}} | Software Engineer -Serghei Iakovlev is a software engineer with 20 years of experience in IT who enjoys finding elegant solutions to non-trivial problems. Serghei focused on the goal and driven by visual sophistication and laser-sharp precision, he take pride in every finished project, and never stop learning along the way. Seghei work as the Head Of Development with 20 teams of 90+ engineers to develop [airSlate](https://airslate.com) --- better nocode workflow automation platform. +Serghei Iakovlev is a software engineer with 20 years of experience in IT who enjoys finding elegant solutions to non-trivial problems. Serghei focused on the goal and driven by visual sophistication and laser-sharp precision, he take pride in every finished project, and never stop learning along the way. Seghei work as the Head Of Development with 20 teams of 90+ engineers to develop {{< link src="https://airslate.com" target="_blank" rel="noopener noreferrer" >}}airSlate{{< /link >}} --- better nocode workflow automation platform. -### [Susanna Allés Torrent](http://susannalles.github.io/) | Hyper philologist +### {{< link src="http://susannalles.github.io/" target="_blank" rel="noopener noreferrer" >}}Susanna Allés Torrent{{< /link >}} | Hyper philologist Susanna teaches Digital Humanities in the Department of Latin American and Iberian Cultures. She earned her Ph.D in Romance Studies at the University of Barcelona in 2012, and completed a M.A. in «Nouvelles technologies appliquées à l’histoire» at the École Nationale des Chartes (Paris). She has taught at the University of Barcelona and she has been a postdoctoral fellow at the Spanish National Research Council (CSIC). Her research explores several aspects of digital humanities, especially, scholarly digital editions, electronic text analysis, intertextuality and text reuse, and digital lexicography. She also works with the intersection of the Iberian Peninsula and Italy in the Middle Ages and the Renaissance, reconstructing cultural and literary networks between the two. -### [Terry Catapano](https://github.com/tcatapano) | Metadata ninja +### {{< link src="https://github.com/tcatapano" target="_blank" rel="noopener noreferrer" >}}Terry Catapano{{< /link >}} | Metadata ninja Terry Catapano is a Librarian in Columbia University Libraries' Digital Program Division. He was Chair of the Society of American Archivists' Schema Development Team, responsible for the development of Encoded Archival Description version 3, and is a member of the ArchivesSpace Technical Advisory Group and the Editorial Board for the Metadata Encoding and Transmission Standard (METS). As Vice President of Plazi Verein, he leads the development of the TaxPub extension of the National Library of Medicine/National Center for Biotechnology Information Journal Publishing DTD, and has worked on digitizing, text mining, and providing open access to the literature of biological systematics, including collaborations with WikiData, the Encylopedia of Life, the Global Biodiversity Information Facility (GBIF), ZooBank, and CERN. -### [Alex Gil](http://www.elotroalex.com/) | Resident minimalist +### {{< link src="http://www.elotroalex.com/" target="_blank" rel="noopener noreferrer" >}}Alex Gil{{< /link >}} | Resident minimalist -Alex is the Digital Scholarship Coordinator for the Humanities and History at Columbia University. He is vice chair of the [Global Outlook::Digital Humanities](http://www.globaloutlookdh.org/) initiative focusing on minimal computing and translation, is one of the founders and directors of [Columbia's Group for Experimental Methods in the Humanities](http://xpmethod.plaintext.in/) and the [Studio@Butler](https://studio.cul.columbia.edu/), and is actively engaged in several digital humanities projects at Columbia and around the world. +Alex is the Digital Scholarship Coordinator for the Humanities and History at Columbia University. He is vice chair of the {{< link src="http://www.globaloutlookdh.org/" target="_blank" rel="noopener noreferrer" >}}Global Outlook::Digital Humanities{{< /link >}} initiative focusing on minimal computing and translation, is one of the founders and directors of {{< link src="http://xpmethod.plaintext.in/" target="_blank" rel="noopener noreferrer" >}}Columbia's Group for Experimental Methods in the Humanities{{< /link >}} and the {{< link src="https://studio.cul.columbia.edu/" target="_blank" rel="noopener noreferrer" >}}Studio@Butler{{< /link >}}, and is actively engaged in several digital humanities projects at Columbia and around the world. -### [Johann Gillium](https://github.com/JohannGillium) | Search master +### {{< link src="https://github.com/JohannGillium" target="_blank" rel="noopener noreferrer" >}}Johann Gillium{{< /link >}} | Search master -After having studied digital humanities at the Ecole nationale des Chartes in Paris, Johann has worked in France as a librarian at the Bibliothèque interuniversaire de Santé, where he most notably contributed to the [Vesalius project](http://www3.biusante.parisdescartes.fr/vesale/debut.htm), the digital edition of several works by the great anatomist Andreas Vesalius. +After having studied digital humanities at the Ecole nationale des Chartes in Paris, Johann has worked in France as a librarian at the Bibliothèque interuniversaire de Santé, where he most notably contributed to the {{< link src="http://www3.biusante.parisdescartes.fr/vesale/debut.htm" target="_blank" rel="noopener noreferrer" >}}Vesalius project{{< /link >}}, the digital edition of several works by the great anatomist Andreas Vesalius. --- ## Acknowledgments -As many open source projects, Ed is the work of community. The project starts with the open web, and everything in between leading to [Hugo](https://gohugo.io/) and the wonderful team who wrangled that Go in our favor. This theme is adopted and finalized with new functionality from [Jekyll](https://jekyllrb.com/) [Ed](https://github.com/minicomp/ed) theme by [Alex Gil](ttps://twitter.com/elotroalex). The original Ed theme stylesheets are built on top of [Lanyon](https://github.com/poole/lanyon), a Jekyll theme based on [Poole](http://getpoole.com), "the Jekyll butler," both created by [Mark Otto](https://github.com/mdo) and distributed with an MIT license. Thanks, Mark, for your helpful streamlining! Special hat tips to brother-in-markdown-arms, [Chris Forster](https://github.com/c-forster), and the generous [Sylvester Keil](https://github.com/inukshuk/) for his work on Jekyll Scholar. +As many open source projects, Ed is the work of community. The project starts with the open web, and everything in between leading to {{< link src="https://gohugo.io/" target="_blank" rel="noopener noreferrer" >}}Hugo{{< /link >}} and the wonderful team who wrangled that Go in our favor. This theme is adopted and finalized with new functionality from {{< link src="https://jekyllrb.com/" target="_blank" rel="noopener noreferrer" >}}Jekyll{{< /link >}} {{< link src="https://github.com/minicomp/ed" target="_blank" rel="noopener noreferrer" >}}Ed{{< /link >}} theme by {{< link src="ttps://twitter.com/elotroalex" target="_blank" rel="noopener noreferrer" >}}Alex Gil{{< /link >}}. The original Ed theme stylesheets are built on top of {{< link src="https://github.com/poole/lanyon" target="_blank" rel="noopener noreferrer" >}}Lanyon{{< /link >}}, a Jekyll theme based on {{< link src="http://getpoole.com" target="_blank" rel="noopener noreferrer" >}}Poole{{< /link >}}, "the Jekyll butler," both created by {{< link src="https://github.com/mdo" target="_blank" rel="noopener noreferrer" >}}Mark Otto{{< /link >}} and distributed with an MIT license. Thanks, Mark, for your helpful streamlining! Special hat tips to brother-in-markdown-arms, {{< link src="https://github.com/c-forster" target="_blank" rel="noopener noreferrer" >}}Chris Forster{{< /link >}}, and the generous {{< link src="https://github.com/inukshuk/" target="_blank" rel="noopener noreferrer" >}}Sylvester Keil{{< /link >}} for his work on Jekyll Scholar. -We are strongly indebted to the research work and conversations stemming out of our [Columbia's Group for Experimental Methods in the Humanities](http://xpmethod.plaintext.in/)—or as we like to call it: #xpmethod; the wonderful international comradery of [GO::DH](http://www.globaloutlookdh.org/); and of course, the support of our [Columbia University Libraries](http://library.columbia.edu/) and its cozy [Studio@Butler](https://studio.cul.columbia.edu/). +We are strongly indebted to the research work and conversations stemming out of our {{< link src="http://xpmethod.plaintext.in/" target="_blank" rel="noopener noreferrer" >}}Columbia's Group for Experimental Methods in the Humanities{{< /link >}}—or as we like to call it: #xpmethod; the wonderful international comradery of {{< link src="http://www.globaloutlookdh.org/" target="_blank" rel="noopener noreferrer" >}}GO::DH{{< /link >}}; and of course, the support of our {{< link src="http://library.columbia.edu/" target="_blank" rel="noopener noreferrer" >}}Columbia University Libraries{{< /link >}} and its cozy {{< link src="https://studio.cul.columbia.edu/" target="_blank" rel="noopener noreferrer" >}}Studio@Butler{{< /link >}}. ...and to the writers that inspire us to scribble notes on the margins we protect with our work. Thank you. diff --git a/exampleSite/content/documentation/index.md b/exampleSite/content/documentation/index.md index 1caff57..5e4460b 100644 --- a/exampleSite/content/documentation/index.md +++ b/exampleSite/content/documentation/index.md @@ -15,15 +15,15 @@ author: Alex Gil This documentation was built with beginners in mind, but has the necessary information for more seasoned producers. -To install and use Ed you will be using your terminal. If you need a refresher, I highly recommend "[The Command Line Crash Course](https://www.computervillage.org/articles/CommandLine.pdf)." Working knowledge of HTML and CSS is also taken for granted. If you're new to HTML and CSS, you may want to check out the relevant courses on [codecademy.com](https://www.codecademy.com/learn/web). +To install and use Ed you will be using your terminal. If you need a refresher, I highly recommend "{{< link src="https://www.computervillage.org/articles/CommandLine.pdf" target="_blank" rel="noopener noreferrer" >}}The Command Line Crash Course{{< /link >}}." Working knowledge of HTML and CSS is also taken for granted. If you're new to HTML and CSS, you may want to check out the relevant courses on {{< link src="https://www.codecademy.com/learn/web" target="_blank" rel="noopener noreferrer" >}}codecademy.com{{< /link >}}. --- ## Installing Ed -Before starting, please be sure that you have [installed Hugo](https://gohugo.io/getting-started/quick-start/#step-1-install-hugo) and [created a new site](https://gohugo.io/getting-started/quick-start/#step-2-create-a-new-site). After that, you are ready to install Ed. +Before starting, please be sure that you have {{< link src="https://gohugo.io/getting-started/quick-start/#step-1-install-hugo" target="_blank" rel="noopener noreferrer" >}}installed Hugo{{< /link >}} and {{< link src="https://gohugo.io/getting-started/quick-start/#step-2-create-a-new-site" target="_blank" rel="noopener noreferrer" >}}created a new site{{< /link >}}. After that, you are ready to install Ed. -The first step to install Ed is to download the source files from GitHub. To do so you must have git installed on your computer. You probably have git already, but if you don't, the easiest way is probably to install [Github Desktop](https://desktop.github.com/) (even though we will be using git and github from the terminal in this tutorial). Mac users may want to ensure they have [Xcode](https://developer.apple.com/xcode/) and its command line tools installed as well. To check if git is running on your system enter the following line on your terminal (remember to ignore the $): +The first step to install Ed is to download the source files from GitHub. To do so you must have git installed on your computer. You probably have git already, but if you don't, the easiest way is probably to install {{< link src="https://desktop.github.com/" target="_blank" rel="noopener noreferrer" >}}Github Desktop{{< /link >}} (even though we will be using git and github from the terminal in this tutorial). Mac users may want to ensure they have {{< link src="https://developer.apple.com/xcode/" target="_blank" rel="noopener noreferrer" >}}Xcode{{< /link >}} and its command line tools installed as well. To check if git is running on your system enter the following line on your terminal (remember to ignore the $): ~~~ bash $ git --version @@ -51,7 +51,7 @@ After installing the theme successfully it requires a just a few more steps to g ### The config file -Take a look inside the [`exampleSite`](https://github.com/sergeyklay/gohugo-theme-ed/tree/master/exampleSite) folder of this theme. You'll find a file called [`config.toml`](https://github.com/sergeyklay/gohugo-theme-ed/blob/master/exampleSite/config.toml). To use it, copy the [`config.toml`](https://github.com/sergeyklay/gohugo-theme-ed/blob/master/exampleSite/config.toml) in the root folder of your Hugo site. Feel free to change the strings in this theme. +Take a look inside the {{< link src="https://github.com/sergeyklay/gohugo-theme-ed/tree/master/exampleSite" target="_blank" rel="noopener noreferrer" >}}`exampleSite`{{< /link >}} folder of this theme. You'll find a file called {{< link src="https://github.com/sergeyklay/gohugo-theme-ed/blob/master/exampleSite/config.toml" target="_blank" rel="noopener noreferrer" >}}`config.toml`{{< /link >}}. To use it, copy the {{< link src="https://github.com/sergeyklay/gohugo-theme-ed/blob/master/exampleSite/config.toml" target="_blank" rel="noopener noreferrer" >}}`config.toml`{{< /link >}} in the root folder of your Hugo site. Feel free to change the strings in this theme. You may need to delete the line: `themesDir = "../.."`, because it's necessary only for theme developers. Also, make sure the theme option is set to `ed`: @@ -73,9 +73,9 @@ Copy the url from your terminal log and paste it into your browser of choice. Th ## Hugo -Ed is a Hugo theme. That means you will need some familiarity with Hugo to take advantage of its full potential. While running a Hugo site is a bit more involved than Wordpress and other similar tools, the payoff in the long term is worth the effort to learn it. If you are new to Hugo, I recommend you take a look at [A Guide to Using Hugo](https://strapi.io/blog/guide-to-using-hugo-site-generator) at *Strapi*, [Host on GitHub](https://gohugo.io/hosting-and-deployment/hosting-on-github/) on *Hugo Documentation Site* and [Hugo's own documentation](https://gohugo.io/documentation/) to start getting a sense of how it works. +Ed is a Hugo theme. That means you will need some familiarity with Hugo to take advantage of its full potential. While running a Hugo site is a bit more involved than Wordpress and other similar tools, the payoff in the long term is worth the effort to learn it. If you are new to Hugo, I recommend you take a look at {{< link src="https://strapi.io/blog/guide-to-using-hugo-site-generator" target="_blank" rel="noopener noreferrer" >}}A Guide to Using Hugo{{< /link >}} at *Strapi*, {{< link src="https://gohugo.io/hosting-and-deployment/hosting-on-github/" target="_blank" rel="noopener noreferrer" >}}Host on GitHub{{< /link >}} on *Hugo Documentation Site* and {{< link src="https://gohugo.io/documentation/" target="_blank" rel="noopener noreferrer" >}}Hugo's own documentation{{< /link >}} to start getting a sense of how it works. -Once you have gone through these tutorials, you can get started using Ed. Remember to always and only edit content files for your site using [a plain text editor](https://en.wikipedia.org/wiki/Text_editor), and *not* a word processor. I'm composing this file using a plain text editor called [Visual Studio Code](https://code.visualstudio.com/). +Once you have gone through these tutorials, you can get started using Ed. Remember to always and only edit content files for your site using {{< link src="https://en.wikipedia.org/wiki/Text_editor" target="_blank" rel="noopener noreferrer" >}}a plain text editor{{< /link >}}, and *not* a word processor. I'm composing this file using a plain text editor called {{< link src="https://code.visualstudio.com/" target="_blank" rel="noopener noreferrer" >}}Visual Studio Code{{< /link >}}. You should make sure that all your texts have the YAML front matter (the information at the top of the file). YAML stands for "YAML Ain't Markup Language" --- no disrespect to XML --- and it's the main way that Hugo handles named data. Here's an example of YAML front matter: @@ -91,9 +91,9 @@ draft: true ## Markdown and CommonMark -Ed is designed for scholars and amateur editors who want to produce either a clean reading edition or a scholarly annotated edition of a text. The main language we use to write in the Hugo environment is called Markdown. To learn more about the Markdown family, see Dennis Tenen and Grant Wythoff's "[Sustainable Authorship in Plain Text using Pandoc and Markdown](http://programminghistorian.org/lessons/sustainable-authorship-in-plain-text-using-pandoc-and-markdown)." +Ed is designed for scholars and amateur editors who want to produce either a clean reading edition or a scholarly annotated edition of a text. The main language we use to write in the Hugo environment is called Markdown. To learn more about the Markdown family, see Dennis Tenen and Grant Wythoff's "{{< link src="http://programminghistorian.org/lessons/sustainable-authorship-in-plain-text-using-pandoc-and-markdown" target="_blank" rel="noopener noreferrer" >}}Sustainable Authorship in Plain Text using Pandoc and Markdown{{< /link >}}." -By default Hugo uses a special Markdown processor called Goldmark. The processor can be said to use it's own 'flavor' of Markdown called CommonMark, and sometimes the Markdown syntax will be different than other flavors of Markdown. CommonMark is a rationalized version of Markdown syntax with a spec whose goal is to remove the ambiguities and inconsistency surrounding the original Markdown specification. It offers a standardized specification that defines the common syntax of the language along with a suite of comprehensive tests to validate Markdown implementations against this specification. You can become familiar with the CommonMark syntax in the [CommonMark documentation](https://spec.commonmark.org/). Another way to become familiar is to examine the sample text source files we provided. +By default Hugo uses a special Markdown processor called Goldmark. The processor can be said to use it's own 'flavor' of Markdown called CommonMark, and sometimes the Markdown syntax will be different than other flavors of Markdown. CommonMark is a rationalized version of Markdown syntax with a spec whose goal is to remove the ambiguities and inconsistency surrounding the original Markdown specification. It offers a standardized specification that defines the common syntax of the language along with a suite of comprehensive tests to validate Markdown implementations against this specification. You can become familiar with the CommonMark syntax in the {{< link src="https://spec.commonmark.org/" target="_blank" rel="noopener noreferrer" >}}CommonMark documentation{{< /link >}}. Another way to become familiar is to examine the sample text source files we provided. --- @@ -230,11 +230,11 @@ The `{.poetry}` tag at the end tells the processor to think of the lines above i ## Pages -Your editions are treated as [collections](https://jekyllrb.com/docs/collections/) in Ed. Other web pages in your site exist outside the `_texts` folder. The homepage, for example, is constructed from the `index.html` file found on the root folder of your Ed project. +Your editions are treated as {{< link src="https://jekyllrb.com/docs/collections/" target="_blank" rel="noopener noreferrer" >}}collections{{< /link >}} in Ed. Other web pages in your site exist outside the `_texts` folder. The homepage, for example, is constructed from the `index.html` file found on the root folder of your Ed project. You will notice that the homepage in particular has a `.html` file ending instead of a `.md` ending. All template files in Jekyll are HTML, and the index behaves as a template file. Although these files are mostly written in HTML, notice that they still contain YAML front matter and liquid tags. To edit the homepage replace the content on the file shipped with Ed, making sure that your changes to `index.html` are written in valid HTML. The same goes for the template files in the `_layouts` folder. -Ed also comes with a search page, `search.html`. This page implements [elastic lunr](http://elasticlunr.com/), "a lightweight full-text search engine in Javascript for browser search and offline search." This simple search page can be useful if you have large collections of texts. If you don't, and don't feel the need, go ahead and delete it along with the `assets/js` folder. +Ed also comes with a search page, `search.html`. This page implements {{< link src="http://elasticlunr.com/" target="_blank" rel="noopener noreferrer" >}}elastic lunr{{< /link >}}, "a lightweight full-text search engine in Javascript for browser search and offline search." This simple search page can be useful if you have large collections of texts. If you don't, and don't feel the need, go ahead and delete it along with the `assets/js` folder. Besides the homepage and the search page, Ed ships with an About page, `about.md` and a documentation page, `documentation.md`, i.e. this page. As you can see, these are regular `.md` files. You can replace the contents of each file using normal kramdown syntax. This also applies to any new page you create, which you should remember to save with an `.md` extension. When editing the `bibliography.md` file, be careful not to replace the liquid tag that generates your bibliography, unless you don't want to have a bibliography at all. @@ -242,7 +242,7 @@ Besides the homepage and the search page, Ed ships with an About page, `about.md ## Tables of Content -You will find three kinds of Tables of Content in Ed. The first example is in the list of Sample Texts in the Homepage. This list is generated using the [Liquid Templating language](http://liquidmarkup.org/). This is one of the major components of Jekyll, and I recommend you deepen your knowledge of it if you want to modify the logic that automates much of Ed. Here is the code that generates the Sample Texts list on the homepage: +You will find three kinds of Tables of Content in Ed. The first example is in the list of Sample Texts in the Homepage. This list is generated using the {{< link src="http://liquidmarkup.org/" target="_blank" rel="noopener noreferrer" >}}Liquid Templating language{{< /link >}}. This is one of the major components of Jekyll, and I recommend you deepen your knowledge of it if you want to modify the logic that automates much of Ed. Here is the code that generates the Sample Texts list on the homepage: ~~~ html
@@ -259,7 +259,7 @@ You will find three kinds of Tables of Content in Ed. The first example is in th
~~~ -As you can see, the liquid tags `{%raw%}{% %}{%endraw%}` and `{%raw%}{{ }}{%endraw%}` are embedded into the HTML. Those with `{%raw%}{% %}{%endraw%}` often use programmatic logic, as is the case here. If you are not already familiar with programming languages, you may need to start elsewhere. I recommend learning Ruby, since this is the language used to build jekyll and jekyll-scholar in the first place (it's also the first programming language I used, so I'm biased). The `{%raw%}{{ }}{%endraw%}` simply pulls data from your project. In the example above it pulls the title from each 'post', i.e. each edited text. As you may have noticed already, we are basically adapting the blogging features of Jekyll to our own ends, what Cuban designer and theorist Ernesto Oroza would call "[technological dissobedience](http://www.ernestooroza.com/)." +As you can see, the liquid tags `{%raw%}{% %}{%endraw%}` and `{%raw%}{{ }}{%endraw%}` are embedded into the HTML. Those with `{%raw%}{% %}{%endraw%}` often use programmatic logic, as is the case here. If you are not already familiar with programming languages, you may need to start elsewhere. I recommend learning Ruby, since this is the language used to build jekyll and jekyll-scholar in the first place (it's also the first programming language I used, so I'm biased). The `{%raw%}{{ }}{%endraw%}` simply pulls data from your project. In the example above it pulls the title from each 'post', i.e. each edited text. As you may have noticed already, we are basically adapting the blogging features of Jekyll to our own ends, what Cuban designer and theorist Ernesto Oroza would call "{{< link src="http://www.ernestooroza.com/" target="_blank" rel="noopener noreferrer" >}}technological dissobedience{{< /link >}}." The second kind of table of content is exemplified in this documentation. If you open the source file for the documentation, you will notice at the top this snippet: @@ -307,14 +307,14 @@ Which should display like this: --- -To help us style and generate bibliographies and citations *automatically*, Ed can use the jekyll-scholar gem by [Sylvester Keil](https://github.com/inukshuk/). To learn more about the gem beyond the basic instructions below, make sure to read the documentation on the [jekyll-scholar](https://github.com/inukshuk/jekyll-scholar) GitHub page. Keep in mind, though, that installing jekyll-scholar and working with it may be a bit difficult for beginners. +To help us style and generate bibliographies and citations *automatically*, Ed can use the jekyll-scholar gem by {{< link src="https://github.com/inukshuk/" target="_blank" rel="noopener noreferrer" >}}Sylvester Keil{{< /link >}}. To learn more about the gem beyond the basic instructions below, make sure to read the documentation on the {{< link src="https://github.com/inukshuk/jekyll-scholar" target="_blank" rel="noopener noreferrer" >}}jekyll-scholar{{< /link >}} GitHub page. Keep in mind, though, that installing jekyll-scholar and working with it may be a bit difficult for beginners. If you can get over the hurdles, jekyll-scholar can save you enormous amounts of time in the long term for your citation and bibliographic work. To begin, you must move the contents of the `jekyll-scholar starter kit` in your `optional` folder into the root folder. This will effectively replace the original `_config.yml` and `Gemfile` files, and add a `_bibliography` folder, and the `bibliography.md` and `Rakefile` files. To enable jekyll-scholar you must re-run `bundle install` again. If everything goes smoothly, you should be able to start using jekyll-scholar at this point. The first thing you may want to do is provide Jekyll with your own bibliographic information in the form of a `.bib` file to replace the content of the `references.bib` file we've provided in the `_bibliography` folder. -To make it easy to create your own version of this file and to keep track of your bibliography for your project, in general I recommend you use [Zotero](http://zotero.org/). To export from Zotero in this format select the references you need from within your Zotero library, right click and select `export in...` and choose the BibLaTeX format. Rename your file to `references.bib` and move it into the `_bibliography` folder. You are, of course, free to create your `references.bib` file using any method you prefer as long as it is a BibTeX file. +To make it easy to create your own version of this file and to keep track of your bibliography for your project, in general I recommend you use {{< link src="http://zotero.org/" target="_blank" rel="noopener noreferrer" >}}Zotero{{< /link >}}. To export from Zotero in this format select the references you need from within your Zotero library, right click and select `export in...` and choose the BibLaTeX format. Rename your file to `references.bib` and move it into the `_bibliography` folder. You are, of course, free to create your `references.bib` file using any method you prefer as long as it is a BibTeX file. Because as textual editors we are more likely than not to use citations in footnotes or pages that contain footnotes, and because footnotes will be necessarily generated at the bottom of the page, Ed also needs a separate page for your Bibliography or works cited. This is the role of the `bibliography.md` file. Feel free to edit the sample text, but make sure to leave the following line intact: @@ -337,7 +337,7 @@ Note that our jekyll-scholar starter kit comes ready for MLA style. To use Chica **Publishing your site on Github Pages with jekyll-scholar** -If you install jekyll-scholar, or most other plugins in Jekyll, you will need a workaround to publish your site on Github Pages, which only runs in 'safe mode.' I've provided a slightly modified version of a `Rakefile` originally created by [Robert Rawlins](https://blog.sorryapp.com/blogging-with-jekyll/2014/01/31/using-jekyll-plugins-on-github-pages.html) that will help you accomplish this task. Once you are ready to publish, switch to your `gh-pages` branch and run the following command: +If you install jekyll-scholar, or most other plugins in Jekyll, you will need a workaround to publish your site on Github Pages, which only runs in 'safe mode.' I've provided a slightly modified version of a `Rakefile` originally created by {{< link src="https://blog.sorryapp.com/blogging-with-jekyll/2014/01/31/using-jekyll-plugins-on-github-pages.html" target="_blank" rel="noopener noreferrer" >}}Robert Rawlins{{< /link >}} that will help you accomplish this task. Once you are ready to publish, switch to your `gh-pages` branch and run the following command: ~~~ bash $ rake ed:publish @@ -348,14 +348,14 @@ $ rake ed:publish ## Tips and Tricks - The folding sidebar menu is generated from the `sidebar.html` file in the `_includes` folder. The top menu items are generated automatically from your pages. The bottom menu items are manually written in HTML. This structure can allow you to add external links. If you don't have that many pages, you may choose to do all the links by hand. -- For more hand-crafted layouts---such as [the title page in *The Narrative of the Life*]({{ site.baseurl }}/texts/narrative/index.html#title-page)---you may choose to work directly with HTML. One of the great advantages of working with the kramdown processor is that we have a lot of flexibility to mix HTML with the kramdown syntax. Note though, that even in the case of the title page, you can achieve these effects using kramdown syntax. +- For more hand-crafted layouts---such as {{< link src="{{ site.baseurl }}/texts/narrative/index.html#title-page" target="_blank" rel="noopener noreferrer" >}}the title page in *The Narrative of the Life*{{< /link >}}---you may choose to work directly with HTML. One of the great advantages of working with the kramdown processor is that we have a lot of flexibility to mix HTML with the kramdown syntax. Note though, that even in the case of the title page, you can achieve these effects using kramdown syntax. - Make sure to add horizontal rules, `---`, to separate sections in your texts. This creates a more pleasant layout. - You can clean unnecessary folders and files from the original Ed package before publishing your site. This will help you reduce overhead. For example, you can erase this page, the sample texts and the `syntax.css` file (used for styling code). - Consider providing tips for your readers on how to make their font bigger or smaller by taking advantage of Command + + and Command + -. Or returning to the top of the page using Command + Up Arrow. Part of the philosophy behind Ed is to avoid duplicating features that are already easily available in most web ecosystems. -- If you want to allow annotations on your site, consider providing a `via.hypothes.is` link. Our sample site can be annotated, for example, using the following link: `https://via.hypothes.is/https://sergeyklay.github.io/gohugo-theme-ed/`, which readers can access on the sidebar. Once you've indicated your own URL in the config file, the link will update automatically. Make sure to visit [hypothes.is](https://hypothes.is/) to learn more. +- If you want to allow annotations on your site, consider providing a `via.hypothes.is` link. Our sample site can be annotated, for example, using the following link: `https://via.hypothes.is/https://sergeyklay.github.io/gohugo-theme-ed/`, which readers can access on the sidebar. Once you've indicated your own URL in the config file, the link will update automatically. Make sure to visit {{< link src="https://hypothes.is/" target="_blank" rel="noopener noreferrer" >}}hypothes.is{{< /link >}} to learn more. - Ed includes metadata in the headers that makes it easier for users of Zotero, and other systems to grab bibliographic information for the site and individual texts. Our metadata functionality may not be enough to generate a full proper citation. Consider providing visible citation information in your about page or homepage. -- Make sure to deepen your knowledge of the building blocks of Ed: Jekyll, YAML and Liquid. A great list of resources can be found in the blog "[Jekyll for Web Designers](http://jameswillweb.github.io/jekyll-for-designers/resources.html)". -- Our base themes Poole/Lanyon allow for easily customization of the interface. You can, for example, switch the position of the sidebar, change the theme colors and overlay options. To learn more check out the [Lanyon documentation](https://github.com/poole/lanyon#themes), and make sure to try the green, `.theme-base-0b`, it's really nice. +- Make sure to deepen your knowledge of the building blocks of Ed: Jekyll, YAML and Liquid. A great list of resources can be found in the blog "{{< link src="http://jameswillweb.github.io/jekyll-for-designers/resources.html" target="_blank" rel="noopener noreferrer" >}}Jekyll for Web Designers{{< /link >}}". +- Our base themes Poole/Lanyon allow for easily customization of the interface. You can, for example, switch the position of the sidebar, change the theme colors and overlay options. To learn more check out the {{< link src="https://github.com/poole/lanyon#themes" target="_blank" rel="noopener noreferrer" >}}Lanyon documentation{{< /link >}}, and make sure to try the green, `.theme-base-0b`, it's really nice. - You can change the look and feel of the site as a whole by changing the `color-scheme` in the `_config.yml` file. If you want to have more granularity, short of editing the `css`, you can change the variable values in the `assets/css/style.scss` file. - In the `optional` folder you will find a sample `xslt` to help you get started converting TEI to Ed. You will also find css for adding pop-up "balloons" or tooltips to your texts. @@ -363,7 +363,7 @@ $ rake ed:publish ## Publishing: A UNIX server -Publishing and Ed edition can be done in one of two ways. One way is to host it on a server you rent, own or have access to. Most mortals pay a hosting provider to host their sites. I recommend [Reclaim Hosting](https://reclaimhosting.com/), which is run by scholars for scholars. If you are affiliated with a university, chances are that your institution provides you with a UNIX account and a bit of server space. Since Jekyll generates a full static site for you, that means you can park it there too. To do so you need to build the site first. If you have been keeping your eye on your project by using `jekyll serve`, chances are you have a current built site in your project folder labelled `_site`. +Publishing and Ed edition can be done in one of two ways. One way is to host it on a server you rent, own or have access to. Most mortals pay a hosting provider to host their sites. I recommend {{< link src="https://reclaimhosting.com/" target="_blank" rel="noopener noreferrer" >}}Reclaim Hosting{{< /link >}}, which is run by scholars for scholars. If you are affiliated with a university, chances are that your institution provides you with a UNIX account and a bit of server space. Since Jekyll generates a full static site for you, that means you can park it there too. To do so you need to build the site first. If you have been keeping your eye on your project by using `jekyll serve`, chances are you have a current built site in your project folder labelled `_site`. If you don't already, you can build one easily by using the following Jekyll command: @@ -377,9 +377,9 @@ Or, again, if you have multiple environments: $ bundle exec jekyll serve ~~~ -Using an FTP client like [Filezilla](https://filezilla-project.org/), or [SSH on your terminal](https://www.siteground.com/tutorials/ssh/), you need to push the contents of the `_site` folder to the folder on your server where you would like your project to exist. Depending on your host provider, you may be able to receive help from the sys admins with this step. +Using an FTP client like {{< link src="https://filezilla-project.org/" target="_blank" rel="noopener noreferrer" >}}Filezilla{{< /link >}}, or {{< link src="https://www.siteground.com/tutorials/ssh/" target="_blank" rel="noopener noreferrer" >}}SSH on your terminal{{< /link >}}, you need to push the contents of the `_site` folder to the folder on your server where you would like your project to exist. Depending on your host provider, you may be able to receive help from the sys admins with this step. -Please refer to the [note below on base urls](#a-note-on-your-base-url) to make sure your new links work on your new site. +Please refer to the {{< link src="#a-note-on-your-base-url" target="_blank" rel="noopener noreferrer" >}}note below on base urls{{< /link >}} to make sure your new links work on your new site. ## Publishing: GitHub pages @@ -388,9 +388,9 @@ Whether you decide to publish on GitHub pages or not, we recommend that you stil If you do decide to use the GitHub pages option, please make sure to read the [note below on base urls](#a-note-on-your-base-url). -To publish on GitHub pages, you must have a copy of the repository in GitHub. That means you also need an account there. Once you've created the repository that you will use, you must link your local repository to the one on GitHub. Notice that because you cloned the original source files from my repository, it will be linked to my repository (to which you don't have writing privileges) until you do this step. Instructions for changing the remote URL can be found [here](https://help.github.com/articles/changing-a-remote-s-url/). +To publish on GitHub pages, you must have a copy of the repository in GitHub. That means you also need an account there. Once you've created the repository that you will use, you must link your local repository to the one on GitHub. Notice that because you cloned the original source files from my repository, it will be linked to my repository (to which you don't have writing privileges) until you do this step. Instructions for changing the remote URL can be found {{< link src="https://help.github.com/articles/changing-a-remote-s-url/" target="_blank" rel="noopener noreferrer" >}}here{{< /link >}}. -The usual way of doing it is to create a different git branch called `gh-pages` within your local repository for your site. This is a branch is published by GitHub by default. GitHub also gives you the option to select [any branch you want to publish](https://github.com/blog/2228-simpler-github-pages-publishing), including the master branch. +The usual way of doing it is to create a different git branch called `gh-pages` within your local repository for your site. This is a branch is published by GitHub by default. GitHub also gives you the option to select {{< link src="https://github.com/blog/2228-simpler-github-pages-publishing" target="_blank" rel="noopener noreferrer" >}}any branch you want to publish{{< /link >}}, including the master branch. In the following I use the gh-pages branch. To create and use that branch use the following command: @@ -404,7 +404,7 @@ Once you are using that branch, you are ready to publish your site. To do so use $ git push origin gh-pages ~~~ -You can now access your site using an address that looks like `http://your-username.github.io/your-project-name`. The sample page for Ed, for example, is hosted at [sergeyklay.github.io/gohugo-theme-ed](https://sergeyklay.github.io/gohugo-theme-ed/). +You can now access your site using an address that looks like `http://your-username.github.io/your-project-name`. The sample page for Ed, for example, is hosted at {{< link src="https://sergeyklay.github.io/gohugo-theme-ed/" target="_blank" rel="noopener noreferrer" >}}sergeyklay.github.io/gohugo-theme-ed{{< /link >}}. **A note on your base url** @@ -418,7 +418,7 @@ baseurl: '' --- -That should do it. If you have suggestions on how to improve Ed, make sure to leave us a line on [our issues page](https://github.com/sergeyklay/gohugo-theme-ed/issues), or send us a pull request. +That should do it. If you have suggestions on how to improve Ed, make sure to leave us a line on {{< link src="https://github.com/sergeyklay/gohugo-theme-ed/issues" target="_blank" rel="noopener noreferrer" >}}our issues page{{< /link >}}, or send us a pull request. Happy editing! diff --git a/exampleSite/content/narratives/narrative.md b/exampleSite/content/narratives/narrative.md index fa82489..f3a3a2b 100644 --- a/exampleSite/content/narratives/narrative.md +++ b/exampleSite/content/narratives/narrative.md @@ -29,7 +29,7 @@ toc: ## Editor's note -This version of *Narrative of the Life of Frederick Douglass* was adapted from *The Project Gutenberg EBook of The Narrative of the Life of Frederick Douglass, by Frederick Douglass*. The [Guttenberg file](http://www.gutenberg.org/) does not tell us which witness was used in making their digital edition. The edition below is only a slightly modified version of the Guttenberg text, and therefore should not be taken too seriously as an edition. I use the text mostly to show a few affordances of using Ed for long form narrative. This page, for example, showcases a different sidebar than the rest of our sample site, with a table of content of the novel generated out of metadata in the source file. In addition, reading morsels of the novel on your different devices can give you a sense of the experience of reading prose using Ed, and shows you an example of the optional sidebar with a table of contents. A few other features of this page are described in more detail in the [Documentation]({{< ref "/documentation" >}}). +This version of *Narrative of the Life of Frederick Douglass* was adapted from *The Project Gutenberg EBook of The Narrative of the Life of Frederick Douglass, by Frederick Douglass*. The {{< link src="http://www.gutenberg.org/" target="_blank" rel="noopener noreferrer" >}}Guttenberg file{{< /link >}} does not tell us which witness was used in making their digital edition. The edition below is only a slightly modified version of the Guttenberg text, and therefore should not be taken too seriously as an edition. I use the text mostly to show a few affordances of using Ed for long form narrative. This page, for example, showcases a different sidebar than the rest of our sample site, with a table of content of the novel generated out of metadata in the source file. In addition, reading morsels of the novel on your different devices can give you a sense of the experience of reading prose using Ed, and shows you an example of the optional sidebar with a table of contents. A few other features of this page are described in more detail in the [Documentation]({{< ref "/documentation" >}}). --- diff --git a/exampleSite/content/poems/a-julia.md b/exampleSite/content/poems/a-julia.md index f07641a..ab6309b 100644 --- a/exampleSite/content/poems/a-julia.md +++ b/exampleSite/content/poems/a-julia.md @@ -12,7 +12,7 @@ source: Ciudad Seva - Mienten, *Julia de Burgos*. Mienten, Julia de Burgos. - La que se alza en mis versos no es tu voz: es mi voz -- porque tú eres [ropaje](http://www.spanishdict.com/translate/ropaje) y la esencia soy yo; y el más +- porque tú eres {{< link src="http://www.spanishdict.com/translate/ropaje" target="_blank" rel="noopener noreferrer" >}}ropaje{{< /link >}} y la esencia soy yo; y el más - profundo abismo se tiende entre las dos. - Tú eres fria muñeca de mentira social, -- cgit v1.2.3