If your browser doesn't redirect you to the new location please - click here, - sorry for the hassles!
- - diff --git a/images/API Consulting Banner.psd b/images/API Consulting Banner.psd deleted file mode 100644 index a01fdb0..0000000 Binary files a/images/API Consulting Banner.psd and /dev/null differ diff --git a/images/api-consulting-banner1.png b/images/api-consulting-banner1.png deleted file mode 100644 index 43c101d..0000000 Binary files a/images/api-consulting-banner1.png and /dev/null differ diff --git a/images/api-consulting-banner2.png b/images/api-consulting-banner2.png deleted file mode 100644 index b8eb3c5..0000000 Binary files a/images/api-consulting-banner2.png and /dev/null differ diff --git a/images/banner1.odg b/images/banner1.odg deleted file mode 100644 index 7d723c4..0000000 Binary files a/images/banner1.odg and /dev/null differ diff --git a/images/banner1.xcf b/images/banner1.xcf deleted file mode 100644 index 3bc740e..0000000 Binary files a/images/banner1.xcf and /dev/null differ diff --git a/index.html b/index.html deleted file mode 100644 index 2b8fc37..0000000 --- a/index.html +++ /dev/null @@ -1,149 +0,0 @@ - - - - - - - -Hey, Fellow REST API Designer!
-Building RESTful web services, like other programming skills is part art, part science. As the Internet industry progresses, creating a REST API becomes more concrete with emerging best practices. As RESTful web services don't follow a prescribed standard except for HTTP, it's important to build your RESTful API in accordance with industry best practices to ease development and increase client adoption.
-Presently, there aren't a lot of REST API guides to help the lonely developer. RestApiTutorial.com is dedicated to tracking REST API best practices and making resources available to enable quick reference and self education for the development crafts-person. We'll discuss both the art and science of creating REST Web services.
-—Todd Fredrich, The REST API Tutor
-Jump in with What Is REST?, an overview of concepts and constraints of the RESTful architecture.
- -
-
-
diff --git a/lessons/httpmethods.html b/lessons/httpmethods.html
deleted file mode 100644
index 44b620b..0000000
--- a/lessons/httpmethods.html
+++ /dev/null
@@ -1,240 +0,0 @@
-
-
-
-
- The HTTP verbs comprise a major portion of our “uniform interface” constraint and provide us the action counterpart to the noun-based resource. The primary or most-commonly-used HTTP verbs (or methods, as they are properly called) are POST, GET, PUT, PATCH, and DELETE. These correspond to create, read, update, and delete (or CRUD) operations, respectively. There are a number of other verbs, too, but are utilized less frequently. Of those less-frequent methods, OPTIONS and HEAD are used more often than others.
-Below is a table summarizing recommended return values of the primary HTTP methods in combination with the resource URIs:
-| HTTP Verb | -CRUD | -Entire Collection (e.g. /customers) | -Specific Item (e.g. /customers/{id}) | -
|---|---|---|---|
| POST | -Create | -201 (Created), 'Location' header with link to /customers/{id} containing new ID. | -404 (Not Found), 409 (Conflict) if resource already exists.. | -
| GET | -Read/Retrieve | -200 (OK), list of customers. Use pagination, sorting and filtering to navigate big lists. | -200 (OK), single customer. 404 (Not Found), if ID not found or invalid. | -
| PUT | -Update/Replace | -405 (Method Not Allowed), unless you want to update/replace every resource in the entire collection. | -200 (OK) or 204 (No Content). 404 (Not Found), if ID not found or invalid. | -
| PATCH | -Update/Modify | -405 (Method Not Allowed), unless you want to modify the collection itself. | -200 (OK) or 204 (No Content). 404 (Not Found), if ID not found or invalid. | -
| DELETE | -Delete | -405 (Method Not Allowed), unless you want to delete the whole collection—not often desirable. | -200 (OK). 404 (Not Found), if ID not found or invalid. | -
Below is a more-detailed discussion of the main HTTP methods. Click on a tab for more information about the desired HTTP method.
- -The POST verb is most-often utilized to **create** new resources. In particular, it's used to create subordinate resources. That is, subordinate to some other (e.g. parent) resource. In other words, when creating a new resource, POST to the parent and the service takes care of associating the new resource with the parent, assigning an ID (new resource URI), etc.
-On successful creation, return HTTP status 201, returning a Location header with a link to the newly-created resource with the 201 HTTP status.
-POST is neither safe nor idempotent. It is therefore recommended for non-idempotent resource requests. Making two identical POST requests will most-likely result in two resources containing the same information.
-Examples:
-The HTTP GET method is used to **read** (or retrieve) a representation of a resource. In the “happy” (or non-error) path, GET returns a representation in XML or JSON and an HTTP response code of 200 (OK). In an error case, it most often returns a 404 (NOT FOUND) or 400 (BAD REQUEST).
-According to the design of the HTTP specification, GET (along with HEAD) requests are used only to read data and not change it. Therefore, when used this way, they are considered safe. That is, they can be called without risk of data modification or corruption—calling it once has the same effect as calling it 10 times, or none at all. Additionally, GET (and HEAD) is idempotent, which means that making multiple identical requests ends up having the same result as a single request.
-Do not expose unsafe operations via GET—it should never modify any resources on the server.
-Examples:
-PUT is most-often utilized for **update** capabilities, PUT-ing to a known resource URI with the request body containing the newly-updated representation of the original resource.
-However, PUT can also be used to create a resource in the case where the resource ID is chosen by the client instead of by the server. In other words, if the PUT is to a URI that contains the value of a non-existent resource ID. Again, the request body contains a resource representation. Many feel this is convoluted and confusing. Consequently, this method of creation should be used sparingly, if at all.
-Alternatively, use POST to create new resources and provide the client-defined ID in the body representation—presumably to a URI that doesn't include the ID of the resource (see POST below).
-On successful update, return 200 (or 204 if not returning any content in the body) from a PUT. If using PUT for create, return HTTP status 201 on successful creation. A body in the response is optional—providing one consumes more bandwidth. It is not necessary to return a link via a Location header in the creation case since the client already set the resource ID.
-PUT is not a safe operation, in that it modifies (or creates) state on the server, but it is idempotent. In other words, if you create or update a resource using PUT and then make that same call again, the resource is still there and still has the same state as it did with the first call.
-If, for instance, calling PUT on a resource increments a counter within the resource, the call is no longer idempotent. Sometimes that happens and it may be enough to document that the call is not idempotent. However, it's recommended to keep PUT requests idempotent. It is strongly recommended to use POST for non-idempotent requests.
-Examples:
-PATCH is used for **modify** capabilities. The PATCH request only needs to contain the changes to the resource, not the complete resource.
-This resembles PUT, but the body contains a set of instructions describing how a resource currently residing on the server should be modified to produce a new version. This means that the PATCH body should not just be a modified part of the resource, but in some kind of patch language like JSON Patch or XML Patch.
-PATCH is neither safe nor idempotent. However, a PATCH request can be issued in such a way as to be idempotent, which also helps prevent bad outcomes from collisions between two PATCH requests on the same resource in a similar time frame. Collisions from multiple PATCH requests may be more dangerous than PUT collisions because some patch formats need to operate from a known base-point or else they will corrupt the resource. Clients using this kind of patch application should use a conditional request such that the request will fail if the resource has been updated since the client last accessed the resource. For example, the client can use a strong ETag in an If-Match header on the PATCH request.
- -Examples:
-DELETE is pretty easy to understand. It is used to **delete** a resource identified by a URI. -
On successful deletion, return HTTP status 200 (OK) along with a response body, perhaps the representation of the deleted item (often demands too much bandwidth), or a wrapped response (see Return Values below). Either that or return HTTP status 204 (NO CONTENT) with no response body. In other words, a 204 status with no body, or the JSEND-style response and HTTP status 200 are the recommended responses.
-HTTP-spec-wise, DELETE operations are idempotent. If you DELETE a resource, it's removed. Repeatedly calling DELETE on that resource ends up the same: the resource is gone. If calling DELETE say, decrements a counter (within the resource), the DELETE call is no longer idempotent. As mentioned previously, usage statistics and measurements may be updated while still considering the service idempotent as long as no resource data is changed. Using POST for non-idempotent resource requests is recommended.
-There is a caveat about DELETE idempotence, however. Calling DELETE on a resource a second time will often return a 404 (NOT FOUND) since it was already removed and therefore is no longer findable. This, by some opinions, makes DELETE operations no longer idempotent, however, the end-state of the resource is the same. Returning a 404 is acceptable and communicates accurately the status of the call.
-Examples:
-
-
-
diff --git a/lessons/idempotency.html b/lessons/idempotency.html
deleted file mode 100644
index 92c3fc2..0000000
--- a/lessons/idempotency.html
+++ /dev/null
@@ -1,140 +0,0 @@
-
-
-
-
- Idempotence is a funky word that often hooks people. Idempotence is sometimes a confusing concept, at least from the academic definition.
-From a RESTful service standpoint, for an operation (or service call) to be idempotent, clients can make that same call repeatedly while producing the same result. In other words, making multiple identical requests has the same effect as making a single request. Note that while idempotent operations produce the same result on the server (no side effects), the response itself may not be the same (e.g. a resource's state may change between requests).
-The PUT and DELETE methods are defined to be idempotent. However, there is a caveat on DELETE. The problem with DELETE, which if successful would normally return a 200 (OK) or 204 (No Content), will often return a 404 (Not Found) on subsequent calls, unless the service is configured to "mark" resources for deletion without actually deleting them. However, when the service actually deletes the resource, the next call will not find the resource to delete it and return a 404. However, the state on the server is the same after each DELETE call, but the response is different.
-GET, HEAD, OPTIONS and TRACE methods are defined as safe, meaning they are only intended for retrieving data. This makes them idempotent as well since multiple, identical requests will behave the same.
-
-
-
diff --git a/lessons/restfulresourcenaming.html b/lessons/restfulresourcenaming.html
deleted file mode 100644
index 20265d2..0000000
--- a/lessons/restfulresourcenaming.html
+++ /dev/null
@@ -1,213 +0,0 @@
-
-
-
-
- In addition to utilizing the HTTP verbs appropriately, resource naming is arguably the most debated and most important concept to grasp when creating an understandable, easily leveraged Web service API. When resources are named well, an API is intuitive and easy to use. Done poorly, that same API can feel klutzy and be difficult to use and understand. Below are a few tips to get you going when creating the resource URIs for your new API.
-Essentially, a RESTful API ends up being simply a collection of URIs, HTTP calls to those URIs and some JSON and/or XML representations of resources, many of which will contain relational links. The RESTful principal of addressability is covered by the URIs. Each resource has its own address or URI—every interesting piece of information the server can provide is exposed as a resource. The constraint of uniform interface is partially addressed by the combination of URIs and HTTP verbs, and using them in line with the standards and conventions.
-In deciding what resources are within your system, name them as nouns as opposed to verbs or actions. In other words, a RESTful URI should refer to a resource that is a thing instead of referring to an action. Nouns have properties as verbs do not, just another distinguishing factor.
-Some example resources are:
-Each resource in a service suite will have at least one URI identifying it. And it's best when that URI makes sense and adequately describes the resource. URIs should follow a predictable, hierarchical structure to enhance understandability and, therefore, usability: predictable in the sense that they're consistent, hierarchical in the sense that data has structure—relationships. This is not a REST rule or constraint, but it enhances the API.
-RESTful APIs are written for consumers. The name and structure of URIs should convey meaning to those consumers. It's often difficult to know what the data boundaries should be, but with understanding of your data, you most-likely are equipped to take a stab and what makes sense to return as a representation to your clients. Design for your clients, not for your data.
-Let's say we're describing an order system with customers, orders, line items, products, etc. Consider the URIs involved in describing the resources in this service suite:
-To insert (create) a new customer in the system, we might use:
- POST http://www.example.com/customers
To read a customer with Customer ID# 33245:
- GET http://www.example.com/customers/33245
- The same URI would be used for PUT and DELETE, to update and delete, respectively.
Here are proposed URIs for products:
- POST http://www.example.com/products
- for creating a new product.
GET|PUT|DELETE http://www.example.com/products/66432
- for reading, updating, deleting product 66432, respectively.
Now, here is where it gets fun... What about creating a new order for a customer? One option might be: POST http://www.example.com/orders And that could work to create an order, but it's arguably outside the context of a customer.
-Because we want to create an order for a customer (note the relationship), this URI perhaps is not as intuitive as it could be. It could be argued that the following URI would offer better clarity: POST http://www.example.com/customers/33245/orders Now we know we're creating an order for customer ID# 33245.
-Now what would the following return?
- GET http://www.example.com/customers/33245/orders
- Probably a list of orders that customer #33245 has created or owns. Note: we may choose to not support DELETE or PUT for that url since it's operating on a collection.
Now, to continue the hierarchical concept, what about the following URI?
- POST http://www.example.com/customers/33245/orders/8769/lineitems
- That might add a line item to order #8769 (which is for customer #33245). Right! GET for that URI might return all the line items for that order. However, if line items don't make sense only in customer context or also make sense outside the context of a customer, we would offer a POST www.example.com/orders/8769/lineitems URI.
Along those lines, because there may be multiple URIs for a given resource, we might also offer a GET http://www.example.com/orders/8769 URI that supports retrieving an order by number without having to know the customer number.
-To go one layer deeper in the hierarchy:
- GET http://www.example.com/customers/33245/orders/8769/lineitems/1
- Might return only the first line item in that same order.
By now you can see how the hierarchy concept works. There aren't any hard and fast rules, only make sure the imposed structure makes sense to consumers of your services. As with everything in the craft of Software Development, naming is critical to success.
-Look at some widely used APIs to get the hang of this and leverage the intuition of your teammates to refine your API resource URIs. Some example APIs are:
-While we've discussed some examples of appropriate resource names, sometimes it's informative to see some anti-patterns. Below are some examples of poor RESTful resource URIs seen in the "wild." These are examples of what not to do!
-First up, often services use a single URI to specify the service interface, using query-string parameters to specify the requested operation and/or HTTP verb. For example to update customer with ID 12345, the request for a JSON body might be:
-GET http://api.example.com/services?op=update_customer&id=12345&format=json
-By now, you're above doing this. Even though the 'services' URL node is a noun, this URL is not self- descriptive as the URI hierarchy is the same for all requests. Plus, it uses GET as the HTTP verb even though we're performing an update. This is counter-intuitive and is painful (even dangerous) to use as a client.
-Here's another example following the same operation of updating a customer:
-GET http://api.example.com/update_customer/12345
-And its evil twin:
-GET http://api.example.com/customers/12345/update
-You'll see this one a lot as you visit other developer's service suites. Note that the developer is attempting to create RESTful resource names and has made some progress. But you're better than this —able to identify the verb phrase in the URL. Notice that we don't need to use the 'update' verb phrase in the URL because we can rely on the HTTP verb to inform that operation. Just to clarify, the following resource URL is redundant:
-PUT http://api.example.com/customers/12345/update
-With both PUT and 'update' in the request, we're offering to confuse our service consumers! Is 'update' the resource? So, we've spent some time beating the horse at this point. I'm certain you understand...
-Let's talk about the debate between the pluralizers and the "singularizers"... Haven't heard of that debate? It does exist. Essentially, it boils down to this question...
-Should URI nodes in your hierarchy be named using singular or plural nouns? For example, should your URI for retrieving a representation of a customer resource look like this:
-GET http://www.example.com/customer/33245 or: - GET http://www.example.com/customers/33245
-There are good arguments on both sides, but the commonly-accepted practice is to always use plurals in node names to keep your API URIs consistent across all HTTP methods. The reasoning is based on the concept that customers are a collection within the service suite and the ID (e.g. 33245) refers to one of those customers in the collection.
-Using this rule, an example multi-node URI using pluralization would look like (emphasis added):
-GET http://www.example.com/customers/33245/orders/8769/lineitems/1
-with 'customers', 'orders', and 'lineitems' URI nodes all being their plural forms.
-This implies that you only really need two base URLs for each root resource. One for creation of the resource within a collection and the second for reading, updating and deleting the resource by its identifier. For example the creation case, using customers as the example, is handled by the following URL:
-POST http://www.example.com/customers
-And the read, update and delete cases are handled by the following:
-GET|PUT|DELETE http://www.example.com/customers/{id}
-As mentioned earlier, there may be multiple URIs for a given resource, but as a minimum full CRUD capabilities are aptly handled with two simple URIs.
-You ask if there is a case where pluralization doesn't make sense. Well, yes, in fact there is. When there isn't a collection concept in play. In other words, it's acceptable to use a singularized resource name when there can only be one of the resource—it's a singleton resource. For example, if there was a single, overarching configuration resource, you might use a singularized noun to represent that:
-GET|PUT|DELETE http://www.example.com/configuration
-Note the lack of a configuration ID and usage of POST verb. And say that there was only one configuration per customer, then the URL might be:
-GET|PUT|DELETE http://www.example.com/customers/12345/configuration
-Again, no ID for the configuration and no POST verb usage. Although, I'm sure that in both of these cases POST usage might be argued to be valid. Well... OK.
-
-
-
diff --git a/lessons/restquicktips.html b/lessons/restquicktips.html
deleted file mode 100644
index b2d848a..0000000
--- a/lessons/restquicktips.html
+++ /dev/null
@@ -1,208 +0,0 @@
-
-
-
-
- Whether it's technically RESTful or not (according to the six constraints mentioned previously), here are a few recommended REST-like concepts. These six quick tips will result in better, more usable services.
-API consumers are capable of sending GET, POST, PUT, and DELETE verbs, which greatly enhance the clarity of a given request.
-Generally, the four primary HTTP verbs are used as follows: -
- GET requests must not change any underlying resource data. Measurements and tracking which update data may still occur, but the resource data identified by the URI should not change. -
-Producing a great API is 80% art and 20% science. Creating a URL hierarchy representing sensible resources is the art part. Having sensible resource names (which are just URL paths, such as /customers/12345/orders) improves the clarity of what a given request does.
-Appropriate resource names provide context for a service request, increasing understandability of the API. Resources are viewed hierarchically via their URI names, offering consumers a friendly, easily-understood hierarchy of resources to leverage in their applications.
-Here are some quick-hit rules for URL path (resource name) design: -
Response status codes are part of the HTTP specification. There are quite a number of them to address the most common situations. In the spirit of having our RESTful services embrace the HTTP specification, our Web APIs should return relevant HTTP status codes. For example, when a resource is successfully created (e.g. from a POST request), the API should return HTTP status code 201. A list of valid HTTP status codes is available here which lists detailed descriptions of each.
-Suggested usages for the "Top 10" HTTP Response Status Codes are as follows: -
Favor JSON support unless you're in a highly-standardized and regulated industry that requires XML, schema validation and namespaces, and offer both JSON and XML unless the costs are staggering. Ideally, let consumers switch between formats using the HTTP Accept header, or by just changing an extension from .xml to .json on the URL.
-Be aware that as soon as we start talking about XML support, we start talking about schemas for validation, namespaces, etc. Unless required by your industry, avoid supporting all that complexity initially, if ever. JSON is designed to be simple, terse and functional. Make your XML look like that if you can.
-In other words, make the XML that is returned more JSON-like — simple and easy to read, without the schema and namespace details present, just data and links. If it ends up being more complex than this, the cost of XML will be staggering. In my experience no one has used XML responses anyway for the last several years, it's just too expensive to consume.
-Note that JSON-Schema offers schema-style validation capabilities, if you need that sort of thing.
-When starting out, it's best to create APIs that mimic the underlying application domain or database architecture of your system. Eventually, you'll want aggregate services that utilize multiple underlying resources to reduce chattiness. However, it's much easier to create larger resources later from individual resources than it is to create fine-grained or individual resources from larger aggregates. Make it easy on yourself and start with small, easily defined resources, providing CRUD functionality on those. You can create those use-case-oriented, chattiness-reducing resources later.
-One of the principles of REST is connectedness—via hypermedia links (search HATEOAS). While services are still useful without them, APIs become more self-descriptive and discoverable when links are returned in the response. At the very least, a 'self' link reference informs clients how the data was or can be retrieved. Additionally, utilize the HTTP Location header to contain a link on resource creation via POST (or PUT). For collections returned in a response that support pagination, 'first', 'last', 'next' and 'prev' links at a minimum are very helpful.
-Regarding linking formats, there are many. The HTTP Web Linking Specification (RFC5988) explains a link as follows: -
a link is a typed connection between two - resources that are identified by Internationalised Resource - Identifiers (IRIs) [RFC3987], and is comprised of: ---
- A link can be viewed as a statement of the form "{context IRI} has a - {relation type} resource at {target IRI}, which has {target - attributes}."- A context IRI,
-- a link relation type
-- a target IRI, and
-- optionally, target attributes.
-
At the very least, place links in the HTTP Link header as recommended in the specification, or embrace a JSON representation of this HTTP link style (such as Atom-style links, see: RFC4287) in your JSON representations. Later, you can layer in more complex linking styles such as HAL+JSON, Siren, Collection+JSON, and/or JSON-LD, etc. as your REST APIs become more mature.
-
-
-
diff --git a/lessons/whatisrest.html b/lessons/whatisrest.html
deleted file mode 100644
index 84d24d1..0000000
--- a/lessons/whatisrest.html
+++ /dev/null
@@ -1,182 +0,0 @@
-
-
-
-
- The REST architectural style describes six constraints. These constraints, applied to the architecture, were originally communicated by Roy Fielding in his doctoral dissertation (see https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm) and defines the basis of RESTful-style.
-The six constraints are: (click the constraint to read more)
-The uniform interface constraint defines the interface between clients and servers. It simplifies and decouples the architecture, which enables each part to evolve independently. The four guiding principles of the uniform interface are:
-Individual resources are identified in requests using URIs as resource identifiers. The resources themselves are conceptually separate from the representations that are returned to the client. For example, the server does not send its database, but rather, some HTML, XML or JSON that represents some database records expressed, for instance, in Finnish and encoded in UTF-8, depending on the details of the request and the server implementation.
-When a client holds a representation of a resource, including any metadata attached, it has enough information to modify or delete the resource on the server, provided it has permission to do so.
-Each message includes enough information to describe how to process the message. For example, which parser to invoke may be specified by an Internet media type (previously known as a MIME type). Responses also explicitly indicate their cache-ability.
-Clients deliver state via body contents, query-string parameters, request headers and the requested URI (the resource name). Services deliver state to clients via body content, response codes, and response headers. This is technically referred-to as hypermedia (or hyperlinks within hypertext).
-Aside from the description above, HATEOS also means that, where necessary, links are contained in the returned body (or headers) to supply the URI for retrieval of the object itself or related objects. We'll talk about this in more detail later.
-The uniform interface that any REST services must provide is fundamental to its design.
-As REST is an acronym for REpresentational State Transfer, statelessness is key. Essentially, what this means is that the necessary state to handle the request is contained within the request itself, whether as part of the URI, query-string parameters, body, or headers. The URI uniquely identifies the resource and the body contains the state (or state change) of that resource. Then after the server does it's processing, the appropriate state, or the piece(s) of state that matter, are communicated back to the client via headers, status and response body.
-Most of us who have been in the industry for a while are accustomed to programming within a container which provides us with the concept of “session” which maintains state across multiple HTTP requests. In REST, the client must include all information for the server to fulfill the request, resending state as necessary if that state must span multiple requests. Statelessness enables greater scalability since the server does not have to maintain, update or communicate that session state. Additionally, load balancers don't have to worry about session affinity for stateless systems.
-So what's the difference between state and a resource? State, or application state, is that which the server cares about to fulfill a request—data necessary for the current session or request. A resource, or resource state, is the data that defines the resource representation—the data stored in the database, for instance. Consider application state to be data that could vary by client, and per request. Resource state, on the other hand, is constant across every client who requests it.
-Ever had back-button issues with a web application where it went AWOL at a certain point because it expected you to do things in a certain order? That's because it violated the statelessness principle. There are cases that don't honor the statelessness principle, such as three-legged OAuth, API call rate limiting, etc. However, make every effort to ensure that application state doesn't span multiple requests of your service(s).
-As on the World Wide Web, clients can cache responses. Responses must therefore, implicitly or explicitly, define themselves as cacheable, or not, to prevent clients reusing stale or inappropriate data in response to further requests. Well-managed caching partially or completely eliminates some client–server interactions, further improving scalability and performance.
-The uniform interface separates clients from servers. This separation of concerns means that, for example, clients are not concerned with data storage, which remains internal to each server, so that the portability of client code is improved. Servers are not concerned with the user interface or user state, so that servers can be simpler and more scalable. Servers and clients may also be replaced and developed independently, as long as the interface is not altered.
-A client cannot ordinarily tell whether it is connected directly to the end server, or to an intermediary along the way. Intermediary servers may improve system scalability by enabling load-balancing and by providing shared caches. Layers may also enforce security policies.
-Servers are able to temporarily extend or customize the functionality of a client by transferring logic to it that it can execute. Examples of this may include compiled components such as Java applets and client-side scripts such as JavaScript.
-Complying with these constraints, and thus conforming to the REST architectural style, will enable any kind of distributed hypermedia system to have desirable emergent properties, such as performance, scalability, simplicity, modifiability, visibility, portability and reliability.
-NOTE: The only optional constraint of REST architecture is code on demand. If a service violates any other constraint, it cannot strictly be referred to as RESTful.
-
-
-
diff --git a/resources.html b/resources.html
deleted file mode 100644
index 65aa1af..0000000
--- a/resources.html
+++ /dev/null
@@ -1,134 +0,0 @@
-
-
-
-
- Get the RESTful Design Best Practices guide (choose your format). This guide reduces the world of RESTful services design into easy-to-follow principles. It also provides several cookbook type recipes in critical areas to increase service usability, reduce confusion during implemenation, as well as improve consistency.
-RestExpress (GitHub). A lightweight microservices framework for Java, RestExpress composes best-of-breed tools to form a lightweight, minimalist Java framework for quickly creating RESTful APIs.
-
-
-
diff --git a/restapiwebinar.html b/restapiwebinar.html
deleted file mode 100644
index 5c85729..0000000
--- a/restapiwebinar.html
+++ /dev/null
@@ -1,167 +0,0 @@
-
-
-
-
-
-
-
- Hey Fellow REST-afarian!
-I'm creating a FREE Webinar about REST API Design and want to answer your most-pressing REST API question.
-Enter your question in the form to the right, along with your email address and I'll answer your questions via the Webinar.
-REST well,
- Todd Fredrich, The REST API Tutor
-
-
diff --git a/restquicktips.html b/restquicktips.html
deleted file mode 100644
index 4bb5f63..0000000
--- a/restquicktips.html
+++ /dev/null
@@ -1,30 +0,0 @@
-
-
- If your browser doesn't redirect you to the new location please - click here, - sorry for the hassles!
- - diff --git a/themes/relearn/.editorconfig b/themes/relearn/.editorconfig new file mode 100644 index 0000000..7849b09 --- /dev/null +++ b/themes/relearn/.editorconfig @@ -0,0 +1,19 @@ +# https://editorconfig.org + +root = true + +[*] +charset = utf-8 +end_of_line = lf +indent_size = 2 +indent_style = space +trim_trailing_whitespace = true + +[*.css] +indent_size = 4 + +[*.js] +insert_final_newline = true + +[*.md] +trim_trailing_whitespace = false diff --git a/themes/relearn/.github/actions/build_site/action.yaml b/themes/relearn/.github/actions/build_site/action.yaml new file mode 100644 index 0000000..38f1b81 --- /dev/null +++ b/themes/relearn/.github/actions/build_site/action.yaml @@ -0,0 +1,14 @@ +name: Build site +description: Builds the Hugo exampleSite for later deploy on GitHub-Pages +runs: + using: composite + steps: + - name: Setup Hugo + uses: peaceiris/actions-hugo@v2 + with: + hugo-version: 'latest' + + - name: Build site + shell: bash + run: | + hugo --source ${GITHUB_WORKSPACE}/exampleSite --destination ${GITHUB_WORKSPACE}/../public --cleanDestinationDir --gc --baseURL https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/ --theme ${GITHUB_WORKSPACE} diff --git a/themes/relearn/.github/actions/check_milestone/action.yaml b/themes/relearn/.github/actions/check_milestone/action.yaml new file mode 100644 index 0000000..2dda0ec --- /dev/null +++ b/themes/relearn/.github/actions/check_milestone/action.yaml @@ -0,0 +1,73 @@ +name: Check milestone +description: Checks if the given milestone and its according tag are valid to be released +inputs: + milestone: + description: Milestone for this release + required: true + github_token: + description: Secret GitHub token + required: true +outputs: + outcome: + description: Result of the check, success or failure + value: ${{ steps.outcome.outputs.outcome }} +runs: + using: composite + steps: + - name: Get tag uniqueness + id: unique_tag + uses: mukunku/tag-exists-action@v1.0.0 + with: + tag: ${{ env.MILESTONE }} + env: + MILESTONE: ${{ inputs.milestone }} + GITHUB_TOKEN: ${{ inputs.github_token }} + + - name: Get closed issues for milestone + id: closed_issues + uses: octokit/graphql-action@v2.x + with: + query: | + query { + search(first: 1, type: ISSUE, query: "user:${{ github.repository_owner }} repo:${{ github.event.repository.name }} milestone:${{ env.MILESTONE }} state:closed") { + issueCount + } + } + env: + MILESTONE: ${{ inputs.milestone }} + GITHUB_TOKEN: ${{ inputs.github_token }} + + - name: Get open issues for milestone + id: open_issues + uses: octokit/graphql-action@v2.x + with: + query: | + query { + search(first: 1, type: ISSUE, query: "user:${{ github.repository_owner }} repo:${{ github.event.repository.name }} milestone:${{ env.MILESTONE }} state:open") { + issueCount + } + } + env: + MILESTONE: ${{ inputs.milestone }} + GITHUB_TOKEN: ${{ inputs.github_token }} + + - name: Set outcome + id: outcome + shell: bash + run: | + if [ "${{ fromJSON(steps.closed_issues.outputs.data).search.issueCount > 0 && fromJSON(steps.open_issues.outputs.data).search.issueCount == 0 && steps.unique_tag.outputs.exists == 'false' }}" = "true" ]; then + echo "::set-output name=outcome::success" + else + echo "::set-output name=outcome::failure" + fi + + - name: Log results and exit + shell: bash + run: | + echo outcome : ${{ steps.outcome.outputs.outcome }} + echo has unique tag : ${{ steps.unique_tag.outputs.exists == 'false' }} + echo has closed issues: ${{ fromJSON(steps.closed_issues.outputs.data).search.issueCount > 0 }} + echo has open issues : ${{ fromJSON(steps.open_issues.outputs.data).search.issueCount > 0 }} + if [ "${{ steps.outcome.outputs.outcome }}" = "failure" ]; then + exit 1 + fi diff --git a/themes/relearn/.github/actions/deploy_site/action.yaml b/themes/relearn/.github/actions/deploy_site/action.yaml new file mode 100644 index 0000000..b03cae0 --- /dev/null +++ b/themes/relearn/.github/actions/deploy_site/action.yaml @@ -0,0 +1,17 @@ +name: Deploy site +description: Deploys a built site on GitHub-Pages +inputs: + github_token: + description: Secret GitHub token + required: true +runs: + using: composite + steps: + - name: Deploy site + uses: peaceiris/actions-gh-pages@v3 + with: + github_token: ${{ env.GITHUB_TOKEN }} + publish_dir: ${{ env.GITHUB_WORKSPACE }}/../public + env: + GITHUB_TOKEN: ${{ inputs.github_token }} + GITHUB_WORKSPACE: ${{ github.workspace }} diff --git a/themes/relearn/.github/actions/release_milestone/action.yaml b/themes/relearn/.github/actions/release_milestone/action.yaml new file mode 100644 index 0000000..901b2c2 --- /dev/null +++ b/themes/relearn/.github/actions/release_milestone/action.yaml @@ -0,0 +1,77 @@ +name: Release milestone +description: Creates a release with changelog and tag out of a given milestone +inputs: + milestone: + description: Milestone for this release + required: true + github_token: + description: Secret GitHub token + required: true +runs: + using: composite + steps: + - name: Setup node + uses: actions/setup-node@v2 + with: + node-version: '16' + + - name: Close milestone + uses: Akkjon/close-milestone@v2 + with: + milestone_name: ${{ env.MILESTONE }} + env: + MILESTONE: ${{ inputs.milestone }} + GITHUB_TOKEN: ${{ inputs.github_token }} + + - name: Create provisionary tag + shell: bash + env: + MILESTONE: ${{ inputs.milestone }} + GITHUB_TOKEN: ${{ inputs.github_token }} + run: | + git config user.name "GitHub Actions Bot" + git config user.email "<>" + git tag --message "" "$MILESTONE" + git push origin "$MILESTONE" + + - name: Update changelog + shell: bash + env: + MILESTONE: ${{ inputs.milestone }} + GITHUB_TOKEN: ${{ inputs.github_token }} + GREN_GITHUB_TOKEN: ${{ inputs.github_token }} + run: | + echo "$MILESTONE" > layouts/partials/version.html + npx github-release-notes@0.17.1 changelog --generate --override --tags=all + git add * + git commit --message "Ship tag $MILESTONE" + git push origin main + + - name: Create final tag + shell: bash + env: + MILESTONE: ${{ inputs.milestone }} + GITHUB_TOKEN: ${{ inputs.github_token }} + run: | + git tag --force --message "" "$MILESTONE" + git push --force origin "$MILESTONE" + + - name: Publish release + shell: bash + env: + MILESTONE: ${{ inputs.milestone }} + GREN_GITHUB_TOKEN: ${{ inputs.github_token }} + run: | + npx github-release-notes@0.17.1 release --tags "$MILESTONE" + + - name: Update version number to mark non-release version + shell: bash + env: + MILESTONE: ${{ inputs.milestone }} + GITHUB_TOKEN: ${{ inputs.github_token }} + GREN_GITHUB_TOKEN: ${{ inputs.github_token }} + run: | + echo "$MILESTONE+tip" > layouts/partials/version.html + git add * + git commit --message "Mark non-release version" + git push origin main diff --git a/themes/relearn/.github/contributing.md b/themes/relearn/.github/contributing.md new file mode 100644 index 0000000..0bcbe39 --- /dev/null +++ b/themes/relearn/.github/contributing.md @@ -0,0 +1,28 @@ +# Guidelines + +## For Development + +- help us putting your code into production by opening a meaningful issue +- stay simple for the user by focusing on the mantra "convention over configuration" +- at installation the site should work reasonable without (m)any configuration +- stay close to the Hugo way +- don't use npm or any preprocessing, our contributors may not be front-end developers +- document new features in exampleSite +- don't break existing features if you don't have to +- remove reported issue from the browser's console +- be compatible to IE11, at least for main functionality, for Javascript this means: + - test in IE11 + - check caniuse.com + - don't use arrow functions + - don't use template literals + - don't use other fancy new ES5/6 stuff + +## For Release + +- create releases following [semver policy](https://semver.org/) +- we are using GitHub actions to create new releases +- a release is based on a milestone named like the release itself - just the version number, eg: 1.1.0 +- remember that there have to be at least one closed issue assigned to the milestone +- the release action only runs successfully if all assigned issues for this milestone are closed +- the milestone itself will be closed during execution of the action +- a once released milestone can not be released again diff --git a/themes/relearn/.github/workflows/build.yaml b/themes/relearn/.github/workflows/build.yaml new file mode 100644 index 0000000..fd9ce5c --- /dev/null +++ b/themes/relearn/.github/workflows/build.yaml @@ -0,0 +1,20 @@ +name: Build + +on: + push: # Build on all pushes but only deploy for main branch + pull_request: # Build on all PRs regardless what branch + workflow_dispatch: # Allow this task to be manually started (you'll never know) + +jobs: + ci: + name: Run build + runs-on: ubuntu-latest + if: github.event_name != 'push' || (github.event_name == 'push' && github.ref != 'refs/heads/main') + steps: + - name: Checkout repo + uses: actions/checkout@v2 + with: + submodules: true # Fetch Hugo themes (true OR recursive) + + - name: Build site + uses: ./.github/actions/build_site diff --git a/themes/relearn/.github/workflows/deploy.yaml b/themes/relearn/.github/workflows/deploy.yaml new file mode 100644 index 0000000..2434748 --- /dev/null +++ b/themes/relearn/.github/workflows/deploy.yaml @@ -0,0 +1,25 @@ +name: Deploy + +on: + push: # Build on all pushes but only deploy for main branch + workflow_dispatch: # Allow this task to be manually started (you'll never know) + +jobs: + deploy: + name: Run deploy + runs-on: ubuntu-latest + if: github.event_name != 'push' || (github.event_name == 'push' && github.ref == 'refs/heads/main') + steps: + - name: Checkout repo + uses: actions/checkout@v2 + with: + submodules: true # Fetch Hugo themes (true OR recursive) + fetch-depth: 0 # Fetch all history for .GitInfo and .Lastmod + + - name: Build site + uses: ./.github/actions/build_site + + - name: Deploy site + uses: ./.github/actions/deploy_site + with: + github_token: ${{ secrets.GITHUB_TOKEN }} diff --git a/themes/relearn/.github/workflows/release.yaml b/themes/relearn/.github/workflows/release.yaml new file mode 100644 index 0000000..1d32b59 --- /dev/null +++ b/themes/relearn/.github/workflows/release.yaml @@ -0,0 +1,42 @@ +name: Release + +on: + workflow_dispatch: + inputs: + milestone: + description: 'Milestone for this release' + required: true + +jobs: + release: + name: Run release + runs-on: ubuntu-latest + steps: + - name: Checkout repo + uses: actions/checkout@v2 + with: + submodules: true # Fetch Hugo themes (true OR recursive) + fetch-depth: 0 # Fetch all history for .GitInfo and .Lastmod + + - name: Check milestone + id: check + uses: ./.github/actions/check_milestone + with: + milestone: ${{ github.event.inputs.milestone }} + github_token: ${{ secrets.GITHUB_TOKEN }} + + - name: Create release + if: ${{ steps.check.outputs.outcome == 'success' }} + uses: ./.github/actions/release_milestone + with: + milestone: ${{ github.event.inputs.milestone }} + github_token: ${{ secrets.GITHUB_TOKEN }} + + # We need to deploy the site again to show the updated changelog + - name: Build site + uses: ./.github/actions/build_site + + - name: Deploy site + uses: ./.github/actions/deploy_site + with: + github_token: ${{ secrets.GITHUB_TOKEN }} diff --git a/themes/relearn/.gitignore b/themes/relearn/.gitignore new file mode 100644 index 0000000..70c1c35 --- /dev/null +++ b/themes/relearn/.gitignore @@ -0,0 +1,5 @@ +.DS_Store +public/ +exampleSite/public +exampleSite/hugo*.exe +.hugo_build.lock diff --git a/themes/relearn/.grenrc.js b/themes/relearn/.grenrc.js new file mode 100644 index 0000000..96ba718 --- /dev/null +++ b/themes/relearn/.grenrc.js @@ -0,0 +1,38 @@ +module.exports = { + changelogFilename: "exampleSite/content/basics/CHANGELOG.md", + dataSource: "milestones", + groupBy: { + "Enhancements": [ + "feature", + ], + "Fixes": [ + "bug" + ], + "Maintenance": [ + "task", + ], + "Uncategorised": [ + "closed", + ], + }, + ignoreLabels: [ + "hugo", + ], + ignoreIssuesWith: [ + "discussion", + "documentation", + "duplicate", + "invalid", + "support", + "wontfix", + ], + ignoreTagsWith: [ + "Relearn", + ], + milestoneMatch: "{{tag_name}}", + onlyMilestones: true, + template: { + group: "\n### {{heading}}\n", + release: ({ body, date, release }) => `## ${release} (` + date.replace( /(\d+)\/(\d+)\/(\d+)/, '$3-$2-$1' ) + `)\n${body}`, + }, +}; diff --git a/themes/relearn/.issuetracker b/themes/relearn/.issuetracker new file mode 100644 index 0000000..6beb6e7 --- /dev/null +++ b/themes/relearn/.issuetracker @@ -0,0 +1,7 @@ +# Integration with Issue Tracker +# +# (note that '\' need to be escaped). + +[issuetracker "GitHub Rule"] + regex = "#(\\d+)" + url = "https://github.com/McShelby/hugo-theme-relearn/issues/$1" diff --git a/themes/relearn/LICENSE b/themes/relearn/LICENSE new file mode 100644 index 0000000..ce8a3bd --- /dev/null +++ b/themes/relearn/LICENSE @@ -0,0 +1,23 @@ +The MIT License (MIT) + +Copyright (c) 2021 Sören Weber +Copyright (c) 2017 Valere JEANTET +Copyright (c) 2016 MATHIEU CORNIC +Copyright (c) 2014 Grav + +Permission is hereby granted, free of charge, to any person obtaining a copy of +this software and associated documentation files (the "Software"), to deal in +the Software without restriction, including without limitation the rights to +use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of +the Software, and to permit persons to whom the Software is furnished to do so, +subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS +FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR +COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER +IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN +CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. diff --git a/themes/relearn/README.md b/themes/relearn/README.md new file mode 100644 index 0000000..e265fca --- /dev/null +++ b/themes/relearn/README.md @@ -0,0 +1,63 @@ +# Hugo Relearn Theme + +A theme for [Hugo](https://gohugo.io/) designed for documentation. + + + +## Motivation + +The theme is a fork of the great [Learn theme](https://github.com/matcornic/hugo-theme-learn) with the aim of fixing long outstanding bugs and adepting to latest Hugo features. As far as possible this theme tries to be a drop-in replacement for the Learn theme. + +## Main features + +- Usable offline, no external dependencies +- Support for Internet Explorer 11 +- Responsive design +- Configurable hidden pages +- Automatic next/prev buttons to navigate through menu entries +- Automatic Search +- Print whole chapters or even the complete site +- Multilingual mode for English, Arabic, Simplified Chinese, Traditional Chinesse, Dutch, French, German, Hindi, Indonesian, Italian, Japanese, Korean, Polish, Portuguese, Russian, Spanish, Turkish, Vietnamese +- Unrestricted menu configuration relating to amount of items and level of nesting +- Font Awesome icons +- Tagging support +- Image resizing, shadow… +- Syntax highlighting +- Attachments files +- List child pages +- Mermaid diagrams for flowcharts, sequences, gantts, pie, etc. +- Swagger UI for OpenAPI Specifications +- Customizable look and feel +- Predefined (light, dark) and customizable color variants +- Buttons +- Tip/Note/Info/Warning boxes +- Expand +- Tabs +- File inclusion +## Installation + +Visit the [installation instructions](https://mcshelby.github.io/hugo-theme-relearn/basics/installation) to learn how to setup the theme in your Hugo installation. + +## Usage + +Visit the [documentation](https://mcshelby.github.io/hugo-theme-relearn/) to learn about all available features and how to use them. + +## Changelog + +See the [changelog](https://mcshelby.github.io/hugo-theme-relearn/basics/history) for a complete list of releases. + +## Contribution + +You are most welcome to contribute to the source code but please visit the [contribution guidelines](https://github.com/McShelby/hugo-theme-relearn/blob/main/.github/contributing.md) first. + +## License + +This theme is licensed under the [MIT License](https://github.com/McShelby/hugo-theme-relearn/blob/main/LICENSE). + +## Credits + +Special thanks to [everyone who has contributed](https://github.com/McShelby/hugo-theme-relearn/graphs/contributors) to this project. + +Many thanks to [Mathieu Cornic](https://github.com/matcornic) for his work on porting the [Learn theme](https://github.com/matcornic/hugo-theme-learn) to Hugo. + +Many thanks to [Andy Miller](https://github.com/rhukster) for initially creating the [Learn theme](https://github.com/getgrav/grav-theme-learn2) for Grav. diff --git a/themes/relearn/archetypes/chapter.md b/themes/relearn/archetypes/chapter.md new file mode 100644 index 0000000..6669355 --- /dev/null +++ b/themes/relearn/archetypes/chapter.md @@ -0,0 +1,12 @@ ++++ +chapter = true +pre = "X. " +title = "{{ replace .Name "-" " " | title }}" +weight = 5 ++++ + +### Chapter X + +# Some Chapter title + +Lorem Ipsum. \ No newline at end of file diff --git a/themes/relearn/archetypes/default.md b/themes/relearn/archetypes/default.md new file mode 100644 index 0000000..0af9e21 --- /dev/null +++ b/themes/relearn/archetypes/default.md @@ -0,0 +1,6 @@ ++++ +title = "{{ replace .Name "-" " " | title }}" +weight = 5 ++++ + +Lorem Ipsum. \ No newline at end of file diff --git a/themes/relearn/config.toml b/themes/relearn/config.toml new file mode 100644 index 0000000..bdbf019 --- /dev/null +++ b/themes/relearn/config.toml @@ -0,0 +1,12 @@ +[module] + [module.hugoVersion] + min = "0.93.0" + +[outputFormats] + [outputFormats.PRINT] + name= "PRINT" + baseName = "index" + path = "_print" + isHTML = true + mediaType = 'text/html' + permalinkable = false diff --git a/themes/relearn/exampleSite/config.toml b/themes/relearn/exampleSite/config.toml new file mode 100644 index 0000000..45a9cfe --- /dev/null +++ b/themes/relearn/exampleSite/config.toml @@ -0,0 +1,162 @@ +# this is a required setting for this theme to appear on https://themes.gohugo.io/ +# change this to a value appropriate for you +baseURL = "https://example.com" +# as the official Hugo documentation recommends, we turn this off for this +# showcase; this allows the published site to be served by both http and https +canonifyURLs = false +# required for official documentation served from subfolder +relativeURLs = false + +# the directory where Hugo reads the themes from; this is specific to your +# installation and most certainly needs be deleted or changed +themesdir = "../.." +# yeah, well, obviously a mandatory setting for your site, if you want to +# use this theme ;-) +theme = "hugo-theme-relearn" + +# the main language of this site; also an automatic pirrrate translation is +# available in this showcase +languageCode = "en" +defaultContentLanguage = "en" +# if you want to get rrrid o' ourrr pirrrates nonsense uncomment th' next line +# disableLanguages = ['pir'] + +# the site's title of this showcase; you should change this ;-) +title = "Hugo Relearn Documentation" + +# settings specific to this theme's features; choose to your likings and +# consult this documentation for explaination +[params] + editURL = "https://github.com/McShelby/hugo-theme-relearn/edit/main/exampleSite/content/" + description = "Documentation for Hugo Relearn Theme" + author = "Sören Weber" + showVisitedLinks = true + collapsibleMenu = true + disableBreadcrumb = false + disableNextPrev = false + disableLandingPageButton = true + titleSeparator = "::" + themeVariant = [ "relearn-light", "relearn-dark", "learn", "neon", "blue", "green", "red" ] + disableSeoHiddenPages = true + # this is for the stylesheet genertor to allow for interactivity in mermaid + # graphs; you usually will not need it and you should remove this for + # security reasons + mermaidInitialize = "{ \"securityLevel\": \"loose\" }" + +[outputs] + # add JSON to the home to support lunr search; This is a mandatory setting + # for the search functionality + # add PRINT to home, section and page to activate feature to print whole + # chapters + home = ["HTML", "RSS", "PRINT", "JSON"] + section = ["HTML", "RSS", "PRINT"] + page = ["HTML", "RSS", "PRINT"] + +[markup] + [markup.highlight] + # if `guessSyntax = true`, there will be no unstyled code even if no language + # was given BUT mermaid code fences will not work anymore! So this is a mandatory + # setting for your site + guessSyntax = false + + # here in this showcase we use our own modified chroma syntax highlightning style + # which is imported in theme-relearn-light.css / theme-relearn-dark.css; + # if you want to use a predefined style instead: + # - remove the following `noClasses` + # - set the following `style` to a predefined style name + # - remove the `@import` of the self-defined chroma stylesheet from your CSS files + # (here eg.: theme-relearn-light.css / theme-relearn-dark.css) + noClasses = false + # style = "tango" + + [markup.goldmark.renderer] + # activated for this showcase to use HTML and JavaScript; decide on your own needs; + # if in doubt, remove this line + unsafe = true + +# allows `hugo server` to display this showcase in IE11; this is used for testing, as we +# are still supporting IE11 - although with degraded experience; if you don't care about +# `hugo server` or browsers of ancient times, fell free to remove this whole block +[server] + [[server.headers]] + for = "**.html" + [server.headers.values] + X-UA-Compatible = "IE=edge" + +# showcase of the menu shortcuts; you can use relative URLs linking +# to your content or use fully-quallified URLs to link outside of +# your project +[Languages] + [Languages.en] + title = "Hugo Relearn Theme" + weight = 1 + languageName = "English" + landingPageURL = "/" + landingPageName = " Home" + + [[Languages.en.menu.shortcuts]] + name = " GitHub repo" + identifier = "ds" + url = "https://github.com/McShelby/hugo-theme-relearn" + weight = 10 + + [[Languages.en.menu.shortcuts]] + name = " Showcases" + url = "more/showcase/" + weight = 11 + + [[Languages.en.menu.shortcuts]] + name = " Hugo Documentation" + identifier = "hugodoc" + url = "https://gohugo.io/" + weight = 20 + + [[Languages.en.menu.shortcuts]] + name = " Credits" + url = "more/credits/" + weight = 30 + + [[Languages.en.menu.shortcuts]] + name = " Tags" + url = "tags/" + weight = 40 + + # this is ourrr way t' showcase th' multilang settings by + # doing autotrrranlat'n of th' english content; we are + # lazy and don't supporrt furrrther trrranslations; arrr, + # don't take it t' serrrious, fello'; it's prrretty hacky and: + # NOT MEANT FOR PRRRODUCTION! ARRR! + + [Languages.pir] + title = "Cap'n Hugo Relearrrn Theme" + weight = 1 + languageName = "Arrr! ☠ Pirrrates ☠" + landingPageURL = "/pir/" + landingPageName = " Arrr! Home" + + [[Languages.pir.menu.shortcuts]] + name = " GitHub repo" + identifier = "ds" + url = "https://github.com/McShelby/hugo-theme-relearn" + weight = 10 + + [[Languages.pir.menu.shortcuts]] + name = " Showcases" + url = "more/showcase/" + weight = 11 + + [[Languages.pir.menu.shortcuts]] + name = " Cap'n Hugo Documentat'n" + identifier = "hugodoc" + url = "https://gohugo.io/" + weight = 20 + + [[Languages.pir.menu.shortcuts]] + name = " Crrredits" + url = "more/credits/" + weight = 30 + + [[Languages.pir.menu.shortcuts]] + name = " Arrr! Tags" + url = "tags/" + weight = 40 diff --git a/themes/relearn/exampleSite/content/_index.en.md b/themes/relearn/exampleSite/content/_index.en.md new file mode 100644 index 0000000..201c72b --- /dev/null +++ b/themes/relearn/exampleSite/content/_index.en.md @@ -0,0 +1,60 @@ ++++ +title = "Hugo Relearn Theme" ++++ + +# Hugo Relearn Theme + +The [Relearn theme](http://github.com/McShelby/hugo-theme-relearn) is a theme for [Hugo](https://gohugo.io/), a static website generator written in Go. Where Hugo is often used for blogs, this theme is designed with documentation in mind. + +{{% notice info %}} +The theme is a fork of the great [Learn theme](https://github.com/matcornic/hugo-theme-learn) with the aim of fixing long outstanding bugs and adepting to latest Hugo features. As far as possible this theme tries to be a drop-in replacement for the Learn theme. +{{% /notice %}} + +## Main features + +{{% notice tip %}} +See [what's new]({{% relref "basics/migration" %}}) within the latest update. +{{% /notice %}} + +- Usable offline, no external dependencies +- Support for Internet Explorer 11 +- Responsive design +- Configurable hidden pages +- Automatic next/prev buttons to navigate through menu entries +- [Automatic Search]({{%relref "basics/configuration#activate-search" %}}) +- [Print]({{%relref "basics/configuration#activate-print-support" %}}) whole chapters or even the complete site +- [Multilingual mode]({{%relref "cont/i18n" %}}) for English, Arabic, Simplified Chinese, Traditional Chinesse, Dutch, French, German, Hindi, Indonesian, Italian, Japanese, Korean, Polish, Portuguese, Russian, Spanish, Turkish, Vietnamese +- [Unrestricted menu configuration]({{%relref "cont/menushortcuts" %}}) relating to amount of items and level of nesting +- [Font Awesome icons]({{%relref "cont/icons" %}}) +- [Tagging support]({{%relref "cont/tags" %}}) +- [Image resizing, shadow...]({{%relref "cont/markdown#images" %}}) +- [Syntax highlighting]({{%relref "cont/syntaxhighlight" %}}) +- [Attachments files]({{%relref "shortcodes/attachments" %}}) +- [List child pages]({{%relref "shortcodes/children" %}}) +- [Mermaid diagrams]({{%relref "shortcodes/mermaid" %}}) for flowcharts, sequences, gantts, pie, etc. +- [Swagger UI]({{%relref "shortcodes/swagger" %}}) for OpenAPI Specifications +- [Customizable look and feel]({{%relref "basics/customization"%}}) +- [Predefined (light, dark) and customizable color variants]({{%relref "basics/generator" %}}) +- [Buttons]({{%relref "shortcodes/button" %}}) +- [Tip/Note/Info/Warning boxes]({{%relref "shortcodes/notice" %}}) +- [Expand]({{%relref "shortcodes/expand" %}}) +- [Tabs]({{%relref "shortcodes/tabs" %}}) +- [File inclusion]({{%relref "shortcodes/include" %}}) + +## Getting support + +To get support, feel free to open a new [discussion topic](https://github.com/McShelby/hugo-theme-relearn/discussions) or [issue](https://github.com/McShelby/hugo-theme-relearn/issues) in the official repository on GitHub. + +## Become a contributor + +Feel free to update this documentation by just clicking the **Edit** link displayed on top right of each page. Your changes will be deployed automatically once they were reviewed. + +You are most welcome to contribute bugfixes or even new features to the source code by making pull requests to the [official repository](https://github.com/McShelby/hugo-theme-relearn) via GitHub. Please visit the [contribution guidelines](https://github.com/McShelby/hugo-theme-relearn/blob/main/.github/contributing.md) first. + +## License + +This theme is licensed under the [MIT License](https://github.com/McShelby/hugo-theme-relearn/blob/main/LICENSE). + +## Credits + +This theme would not be possible without the work of many others. See the [credits]({{%relref "more/credits" %}}) for a detailed list. diff --git a/themes/relearn/exampleSite/content/_index.pir.md b/themes/relearn/exampleSite/content/_index.pir.md new file mode 100644 index 0000000..daad3e0 --- /dev/null +++ b/themes/relearn/exampleSite/content/_index.pir.md @@ -0,0 +1,4 @@ ++++ +title = "Cap'n Hugo Relearrrn Theme" ++++ +{{< piratify >}} \ No newline at end of file diff --git a/themes/relearn/exampleSite/content/basics/CHANGELOG.md b/themes/relearn/exampleSite/content/basics/CHANGELOG.md new file mode 100644 index 0000000..6f07176 --- /dev/null +++ b/themes/relearn/exampleSite/content/basics/CHANGELOG.md @@ -0,0 +1,548 @@ +# Changelog + +## 4.0.3 (2022-06-05) + +### Enhancements + +- [**feature**] toc: add scrollbar [#262](https://github.com/McShelby/hugo-theme-relearn/issues/262) + +--- + +## 4.0.2 (2022-06-05) + +### Fixes + +- [**bug**] theme: let browser scroll page on CTRL+f [#242](https://github.com/McShelby/hugo-theme-relearn/issues/242) + +--- + +## 4.0.1 (2022-06-05) +*No changelog for this release.* + +--- + +## 4.0.0 (2022-06-05) + +### Enhancements + +- [**feature**] shortcodes: add named parameter if missing [#260](https://github.com/McShelby/hugo-theme-relearn/issues/260) +- [**feature**][**breaking**] theme: remove --MAIN-ANCHOR-color from stylesheet [#256](https://github.com/McShelby/hugo-theme-relearn/issues/256) +- [**feature**] i18n: add italian translation [#254](https://github.com/McShelby/hugo-theme-relearn/issues/254) +- [**feature**] attachments: support for brand colors [#252](https://github.com/McShelby/hugo-theme-relearn/issues/252) +- [**feature**] notice: support for brand colors [#251](https://github.com/McShelby/hugo-theme-relearn/issues/251) +- [**feature**][**breaking**] config: remove custom_css [#248](https://github.com/McShelby/hugo-theme-relearn/issues/248) +- [**feature**] theme: use proper file extension for page-meta.go [#246](https://github.com/McShelby/hugo-theme-relearn/issues/246) +- [**feature**] variant: add support for brand color variables [#239](https://github.com/McShelby/hugo-theme-relearn/issues/239) +- [**feature**] i18n: add polish translation [#237](https://github.com/McShelby/hugo-theme-relearn/issues/237) + +### Fixes + +- [**bug**] shortcodes: accept boolean parameters if given as string [#261](https://github.com/McShelby/hugo-theme-relearn/issues/261) +- [**bug**] print: adjust button and tab size [#259](https://github.com/McShelby/hugo-theme-relearn/issues/259) +- [**bug**] print: show Mermaid if requested in frontmatter [#255](https://github.com/McShelby/hugo-theme-relearn/issues/255) +- [**bug**] theme: adjust thin scrollbar slider [#244](https://github.com/McShelby/hugo-theme-relearn/issues/244) +- [**bug**] mobile: fix broken scrollbar [#243](https://github.com/McShelby/hugo-theme-relearn/issues/243) +- [**bug**] theme: fix display of tooltip for heading anchor [#241](https://github.com/McShelby/hugo-theme-relearn/issues/241) + +--- + +## 3.4.1 (2022-04-03) + +### Fixes + +- [**bug**] theme: fix IE11 incompatiblities [#234](https://github.com/McShelby/hugo-theme-relearn/issues/234) + +--- + +## 3.4.0 (2022-04-03) + +### Enhancements + +- [**feature**] i18n: add traditional chinese translation [#233](https://github.com/McShelby/hugo-theme-relearn/issues/233) +- [**feature**] menu: expand/collapse menu items without navigation [#231](https://github.com/McShelby/hugo-theme-relearn/issues/231) +- [**feature**] print: add option to print whole chapter [#230](https://github.com/McShelby/hugo-theme-relearn/issues/230) +- [**feature**][**breaking**] theme: apply user supplied content footer below content [#229](https://github.com/McShelby/hugo-theme-relearn/issues/229) + +### Fixes + +- [**bug**] theme: scroll to heading on initial load [#232](https://github.com/McShelby/hugo-theme-relearn/issues/232) + +--- + +## 3.3.0 (2022-03-28) + +### Enhancements + +- [**feature**] theme: add CSS font variables [#227](https://github.com/McShelby/hugo-theme-relearn/issues/227) +- [**feature**] swagger: add support for oas/swagger documentation [#226](https://github.com/McShelby/hugo-theme-relearn/issues/226) + +### Fixes + +- [**bug**] variant: make variant switch work on slow networks [#228](https://github.com/McShelby/hugo-theme-relearn/issues/228) + +--- + +## 3.2.1 (2022-03-25) + +### Fixes + +- [**bug**] print: fix minor inconsistencies [#225](https://github.com/McShelby/hugo-theme-relearn/issues/225) +- [**bug**] print: show more than just the title page [#224](https://github.com/McShelby/hugo-theme-relearn/issues/224) +- [**bug**] theme: align content scrollbar to the right on big screens [#223](https://github.com/McShelby/hugo-theme-relearn/issues/223) + +--- + +## 3.2.0 (2022-03-19) + +### Enhancements + +- [**feature**][**change**] mermaid: support differing themes for color variant switch [#219](https://github.com/McShelby/hugo-theme-relearn/issues/219) +- [**feature**] mermaid: load javascript on demand [#218](https://github.com/McShelby/hugo-theme-relearn/issues/218) + +### Maintenance + +- [**task**] mermaid: update to 8.14.0 [#220](https://github.com/McShelby/hugo-theme-relearn/issues/220) + +--- + +## 3.1.1 (2022-03-16) + +### Enhancements + +- [**feature**] i18n: add korean translation [#217](https://github.com/McShelby/hugo-theme-relearn/issues/217) + +--- + +## 3.1.0 (2022-03-15) + +### Enhancements + +- [**feature**] notice: add icon parameter [#212](https://github.com/McShelby/hugo-theme-relearn/issues/212) +- [**feature**] mobile: remove breadcrumb ellipsis [#211](https://github.com/McShelby/hugo-theme-relearn/issues/211) + +### Fixes + +- [**bug**] theme: make storage of multiple Hugo sites on same server distinct [#214](https://github.com/McShelby/hugo-theme-relearn/issues/214) +- [**bug**] variant: switch breadcrumb color in Chrome [#213](https://github.com/McShelby/hugo-theme-relearn/issues/213) +- [**bug**] mobile: improve behavior of sidebar menu [#210](https://github.com/McShelby/hugo-theme-relearn/issues/210) + +--- + +## 3.0.4 (2022-02-24) + +### Enhancements + +- [**feature**] theme: improve font loading [#201](https://github.com/McShelby/hugo-theme-relearn/issues/201) +- [**feature**][**change**] variant: fix inconsistent color variable naming [#200](https://github.com/McShelby/hugo-theme-relearn/issues/200) + +### Fixes + +- [**bug**] variant: fix occasional fail when resetting generator [#208](https://github.com/McShelby/hugo-theme-relearn/issues/208) +- [**bug**] docs: don't move header on logo hover in IE11 [#207](https://github.com/McShelby/hugo-theme-relearn/issues/207) +- [**bug**] variant: avoid flash of menu header when non default variant is active [#206](https://github.com/McShelby/hugo-theme-relearn/issues/206) +- [**bug**] theme: fix wrong HTML closing tag order in chapters [#205](https://github.com/McShelby/hugo-theme-relearn/issues/205) +- [**bug**] theme: adjust breadcrumb and title for empty home page titles [#202](https://github.com/McShelby/hugo-theme-relearn/issues/202) + +--- + +## 3.0.3 (2022-02-23) + +### Enhancements + +- [**feature**] tags: show tag count in taxonomy list [#195](https://github.com/McShelby/hugo-theme-relearn/issues/195) + +### Fixes + +- [**bug**] theme: remove Hugo build warning if page is not file based [#197](https://github.com/McShelby/hugo-theme-relearn/issues/197) +- [**bug**] tags: adhere to titleSeparator [#196](https://github.com/McShelby/hugo-theme-relearn/issues/196) +- [**bug**] theme: hide footer divider and variant selector in IE11 [#194](https://github.com/McShelby/hugo-theme-relearn/issues/194) + +--- + +## 3.0.2 (2022-02-23) + +### Enhancements + +- [**feature**] tags: sort by name [#193](https://github.com/McShelby/hugo-theme-relearn/issues/193) + +--- + +## 3.0.1 (2022-02-23) + +### Enhancements + +- [**feature**] children: set containerstyle automatically according to style [#192](https://github.com/McShelby/hugo-theme-relearn/issues/192) + +### Fixes + +- [**bug**] theme: revert fontawsome to version 5 for IE11 compat [#191](https://github.com/McShelby/hugo-theme-relearn/issues/191) + +--- + +## 3.0.0 (2022-02-22) + +### Enhancements + +- [**feature**] variant: build a variant generator [#188](https://github.com/McShelby/hugo-theme-relearn/issues/188) +- [**feature**] nav: only show toc if the page has headings [#182](https://github.com/McShelby/hugo-theme-relearn/issues/182) +- [**feature**][**breaking**] theme: change default colors to Relearn defaults [#181](https://github.com/McShelby/hugo-theme-relearn/issues/181) +- [**feature**] variant: add a variant selector [#178](https://github.com/McShelby/hugo-theme-relearn/issues/178) +- [**feature**][**breaking**] menu: rework footer UX [#177](https://github.com/McShelby/hugo-theme-relearn/issues/177) +- [**feature**] theme: support for dark mode [#175](https://github.com/McShelby/hugo-theme-relearn/issues/175) +- [**feature**] docs: use light syntax highlightning theme [#174](https://github.com/McShelby/hugo-theme-relearn/issues/174) +- [**feature**] notice: tweak dull colors [#173](https://github.com/McShelby/hugo-theme-relearn/issues/173) +- [**feature**] theme: rework header UX [#151](https://github.com/McShelby/hugo-theme-relearn/issues/151) + +### Fixes + +- [**bug**] search: remove additional X in filled out search box in IE11 [#190](https://github.com/McShelby/hugo-theme-relearn/issues/190) +- [**bug**] clipboard: localize tooltips [#186](https://github.com/McShelby/hugo-theme-relearn/issues/186) +- [**bug**] print: hide sidebar on Mac [#183](https://github.com/McShelby/hugo-theme-relearn/issues/183) +- [**bug**] menu: fix scrollbar height [#180](https://github.com/McShelby/hugo-theme-relearn/issues/180) +- [**bug**][**change**] search: fix color change for icons on hover [#176](https://github.com/McShelby/hugo-theme-relearn/issues/176) + +--- + +## 2.9.6 (2022-02-07) + +### Fixes + +- [**bug**] menu: remove debug output [#171](https://github.com/McShelby/hugo-theme-relearn/issues/171) + +--- + +## 2.9.5 (2022-02-07) + +### Fixes + +- [**bug**] menu: let arrow navigation respect ordersectionsby configuration [#170](https://github.com/McShelby/hugo-theme-relearn/issues/170) + +--- + +## 2.9.4 (2022-02-06) + +### Fixes + +- [**bug**] exampleSite: fix links in official documentation [#168](https://github.com/McShelby/hugo-theme-relearn/issues/168) + +--- + +## 2.9.3 (2022-02-06) + +### Fixes + +- [**bug**] menu: invalid URL when the shortcut is an internal link [#163](https://github.com/McShelby/hugo-theme-relearn/issues/163) + +--- + +## 2.9.2 (2021-11-26) + +### Enhancements + +- [**feature**] theme: add theme version info to head [#158](https://github.com/McShelby/hugo-theme-relearn/issues/158) + +### Fixes + +- [**bug**] theme: fix selection of *.ico files as favicons [#160](https://github.com/McShelby/hugo-theme-relearn/issues/160) + +--- + +## 2.9.1 (2021-11-22) + +### Fixes + +- [**bug**] menu: fix significantly low performance for collecting of meta info [#157](https://github.com/McShelby/hugo-theme-relearn/issues/157) + +--- + +## 2.9.0 (2021-11-19) + +### Fixes + +- [**bug**][**breaking**] relref: fix inconsistent behavior [#156](https://github.com/McShelby/hugo-theme-relearn/issues/156) +- [**bug**] search: make dropdown stick to search field when scrolling [#155](https://github.com/McShelby/hugo-theme-relearn/issues/155) +- [**bug**] menu: align long text properly [#154](https://github.com/McShelby/hugo-theme-relearn/issues/154) +- [**bug**] copyToClipBoard: add missing right border for inline code if `disableInlineCopyToClipBoard=true` [#153](https://github.com/McShelby/hugo-theme-relearn/issues/153) +- [**bug**] menu: show hidden sibling pages reliably [#152](https://github.com/McShelby/hugo-theme-relearn/issues/152) +- [**bug**] menu: bring active item in sight for large menus [#149](https://github.com/McShelby/hugo-theme-relearn/issues/149) + +--- + +## 2.8.3 (2021-11-09) + +### Fixes + +- [**bug**] mermaid: let zoom reset to initial size [#145](https://github.com/McShelby/hugo-theme-relearn/issues/145) +- [**bug**] mermaid: remove whitespace from big graphs [#143](https://github.com/McShelby/hugo-theme-relearn/issues/143) + +--- + +## 2.8.2 (2021-11-08) + +### Fixes + +- [**bug**] mermaid: always load javascript to avoid break if code fences are used [#142](https://github.com/McShelby/hugo-theme-relearn/issues/142) + +--- + +## 2.8.1 (2021-11-04) + +### Fixes + +- [**bug**] search: don't break JS in multilang setup if search is disabled [#140](https://github.com/McShelby/hugo-theme-relearn/issues/140) + +--- + +## 2.8.0 (2021-11-03) + +### Enhancements + +- [**feature**] toc: make disableTOC globally available via config.toml [#133](https://github.com/McShelby/hugo-theme-relearn/issues/133) +- [**feature**] mermaid: only load javascript if necessary [#95](https://github.com/McShelby/hugo-theme-relearn/issues/95) +- [**feature**][**change**] theme: switch font [#83](https://github.com/McShelby/hugo-theme-relearn/issues/83) +- [**feature**] theme: make favicon configurable [#2](https://github.com/McShelby/hugo-theme-relearn/issues/2) + +### Fixes + +- [**bug**] mermaid: assert that window.mermaid is actually mermaid [#136](https://github.com/McShelby/hugo-theme-relearn/issues/136) +- [**bug**] menu: remove usage of Hugos UniqueID [#131](https://github.com/McShelby/hugo-theme-relearn/issues/131) +- [**bug**] theme: reduce margin for children shortcode [#130](https://github.com/McShelby/hugo-theme-relearn/issues/130) +- [**bug**] theme: left-align h3 in chapters [#129](https://github.com/McShelby/hugo-theme-relearn/issues/129) +- [**bug**] theme: align copy link to clipboard [#128](https://github.com/McShelby/hugo-theme-relearn/issues/128) + +--- + +## 2.7.0 (2021-10-24) + +### Enhancements + +- [**feature**] notice: support custom titles [#124](https://github.com/McShelby/hugo-theme-relearn/issues/124) + +--- + +## 2.6.0 (2021-10-21) + +### Fixes + +- [**bug**] theme: generate correct links if theme served from subdirectory [#120](https://github.com/McShelby/hugo-theme-relearn/issues/120) + +--- + +## 2.5.1 (2021-10-12) + +### Fixes + +- [**bug**] security: fix XSS for malicioius image URLs [#117](https://github.com/McShelby/hugo-theme-relearn/issues/117) + +--- + +## 2.5.0 (2021-10-08) + +### Enhancements + +- [**feature**][**change**] syntax highlight: provide default colors for unknown languages [#113](https://github.com/McShelby/hugo-theme-relearn/issues/113) + +### Fixes + +- [**bug**] security: fix XSS for malicioius URLs [#114](https://github.com/McShelby/hugo-theme-relearn/issues/114) +- [**bug**] menu: write correct local shortcut links [#112](https://github.com/McShelby/hugo-theme-relearn/issues/112) + +--- + +## 2.4.1 (2021-10-07) + +### Fixes + +- [**bug**] theme: remove runtime styles from print [#111](https://github.com/McShelby/hugo-theme-relearn/issues/111) + +--- + +## 2.4.0 (2021-10-07) + +### Enhancements + +- [**feature**] lang: add vietnamese translation [#109](https://github.com/McShelby/hugo-theme-relearn/issues/109) +- [**feature**][**change**] theme: simplify stylesheet for color variants [#107](https://github.com/McShelby/hugo-theme-relearn/issues/107) +- [**feature**] hidden pages: remove from RSS feed, JSON, taxonomy etc [#102](https://github.com/McShelby/hugo-theme-relearn/issues/102) +- [**feature**] theme: announce alternative content in header [#101](https://github.com/McShelby/hugo-theme-relearn/issues/101) +- [**feature**] menu: frontmatter option to change sort predicate [#98](https://github.com/McShelby/hugo-theme-relearn/issues/98) +- [**feature**] menu: add default setting for menu expansion [#97](https://github.com/McShelby/hugo-theme-relearn/issues/97) +- [**feature**] theme: improve print style [#93](https://github.com/McShelby/hugo-theme-relearn/issues/93) +- [**feature**] theme: improve style [#92](https://github.com/McShelby/hugo-theme-relearn/issues/92) + +### Fixes + +- [**bug**] include: don't generate additional HTML if file should be displayed "as is" [#110](https://github.com/McShelby/hugo-theme-relearn/issues/110) +- [**bug**] attachments: fix broken links if multilang config is used [#105](https://github.com/McShelby/hugo-theme-relearn/issues/105) +- [**bug**] theme: fix sticky header to remove horizontal scrollbar [#82](https://github.com/McShelby/hugo-theme-relearn/issues/82) + +### Maintenance + +- [**task**] chore: update fontawesome [#94](https://github.com/McShelby/hugo-theme-relearn/issues/94) + +--- + +## 2.3.2 (2021-09-20) + +### Fixes + +- [**bug**] docs: rename history pirate translation [#91](https://github.com/McShelby/hugo-theme-relearn/issues/91) + +--- + +## 2.3.1 (2021-09-20) + +### Fixes + +- [**bug**] docs: rename english pirate translation to avoid crash on rendering [#90](https://github.com/McShelby/hugo-theme-relearn/issues/90) + +--- + +## 2.3.0 (2021-09-13) + +### Fixes + +- [**bug**] theme: fix usage of section element [#88](https://github.com/McShelby/hugo-theme-relearn/issues/88) + +### Maintenance + +- [**task**] theme: ensure IE11 compatiblity [#89](https://github.com/McShelby/hugo-theme-relearn/issues/89) +- [**task**] docs: Arrr! showcase multilang featurrre [#87](https://github.com/McShelby/hugo-theme-relearn/issues/87) + +--- + +## 2.2.0 (2021-09-09) + +### Enhancements + +- [**feature**] sitemap: hide hidden pages from sitemap and SEO indexing [#85](https://github.com/McShelby/hugo-theme-relearn/issues/85) + +### Fixes + +- [**bug**] theme: fix showVisitedLinks in case Hugo is configured to modify relative URLs [#86](https://github.com/McShelby/hugo-theme-relearn/issues/86) + +### Maintenance + +- [**task**] theme: switch from data-vocabulary to schema [#84](https://github.com/McShelby/hugo-theme-relearn/issues/84) + +--- + +## 2.1.0 (2021-09-07) + +### Enhancements + +- [**feature**] search: open expand if it contains search term [#80](https://github.com/McShelby/hugo-theme-relearn/issues/80) +- [**feature**] menu: scroll active item into view [#79](https://github.com/McShelby/hugo-theme-relearn/issues/79) +- [**feature**] search: disable search in hidden pages [#76](https://github.com/McShelby/hugo-theme-relearn/issues/76) +- [**feature**] search: improve readablility of index.json [#75](https://github.com/McShelby/hugo-theme-relearn/issues/75) +- [**feature**] search: increase performance [#74](https://github.com/McShelby/hugo-theme-relearn/issues/74) +- [**feature**] search: improve search context preview [#73](https://github.com/McShelby/hugo-theme-relearn/issues/73) + +### Fixes + +- [**bug**][**change**] search: hide non-site content [#81](https://github.com/McShelby/hugo-theme-relearn/issues/81) +- [**bug**] menu: always hide hidden sub pages [#77](https://github.com/McShelby/hugo-theme-relearn/issues/77) + +--- + +## 2.0.0 (2021-08-28) + +### Enhancements + +- [**feature**] tabs: enhance styling [#65](https://github.com/McShelby/hugo-theme-relearn/issues/65) +- [**feature**] theme: improve readability [#64](https://github.com/McShelby/hugo-theme-relearn/issues/64) +- [**feature**] menu: show hidden pages if accessed directly [#60](https://github.com/McShelby/hugo-theme-relearn/issues/60) +- [**feature**][**change**] theme: treat pages without title as hidden [#59](https://github.com/McShelby/hugo-theme-relearn/issues/59) +- [**feature**] search: show search results if field gains focus [#58](https://github.com/McShelby/hugo-theme-relearn/issues/58) +- [**feature**] theme: add partial templates for pre/post menu entries [#56](https://github.com/McShelby/hugo-theme-relearn/issues/56) +- [**feature**] theme: make chapter archetype more readable [#55](https://github.com/McShelby/hugo-theme-relearn/issues/55) +- [**feature**] children: add parameter for container style [#53](https://github.com/McShelby/hugo-theme-relearn/issues/53) +- [**feature**] theme: make content a template [#50](https://github.com/McShelby/hugo-theme-relearn/issues/50) +- [**feature**] menu: control menu expansion with alwaysopen parameter [#49](https://github.com/McShelby/hugo-theme-relearn/issues/49) +- [**feature**] include: new shortcode to include other files [#43](https://github.com/McShelby/hugo-theme-relearn/issues/43) +- [**feature**] theme: adjust print styles [#35](https://github.com/McShelby/hugo-theme-relearn/issues/35) +- [**feature**][**change**] code highligher: switch to standard hugo highlighter [#32](https://github.com/McShelby/hugo-theme-relearn/issues/32) + +### Fixes + +- [**bug**][**change**] arrow-nav: default sorting ignores ordersectionsby [#63](https://github.com/McShelby/hugo-theme-relearn/issues/63) +- [**bug**][**change**] children: default sorting ignores ordersectionsby [#62](https://github.com/McShelby/hugo-theme-relearn/issues/62) +- [**bug**][**change**] arrow-nav: fix broken links on (and below) hidden pages [#61](https://github.com/McShelby/hugo-theme-relearn/issues/61) +- [**bug**] theme: remove superflous singular taxonomy from taxonomy title [#46](https://github.com/McShelby/hugo-theme-relearn/issues/46) +- [**bug**][**change**] theme: missing --MENU-HOME-LINK-HOVER-color in documentation [#45](https://github.com/McShelby/hugo-theme-relearn/issues/45) +- [**bug**] theme: fix home link when base URL has some path [#44](https://github.com/McShelby/hugo-theme-relearn/issues/44) + +### Maintenance + +- [**task**] docs: include changelog in exampleSite [#33](https://github.com/McShelby/hugo-theme-relearn/issues/33) + +--- + +## 1.2.0 (2021-07-26) + +### Enhancements + +- [**feature**] theme: adjust copy-to-clipboard [#29](https://github.com/McShelby/hugo-theme-relearn/issues/29) +- [**feature**] attachments: adjust style between notice boxes and attachments [#28](https://github.com/McShelby/hugo-theme-relearn/issues/28) +- [**feature**] theme: adjust blockquote contrast [#27](https://github.com/McShelby/hugo-theme-relearn/issues/27) +- [**feature**] expand: add option to open on page load [#25](https://github.com/McShelby/hugo-theme-relearn/issues/25) +- [**feature**] expand: rework styling [#24](https://github.com/McShelby/hugo-theme-relearn/issues/24) +- [**feature**] attachments: sort output [#23](https://github.com/McShelby/hugo-theme-relearn/issues/23) +- [**feature**] notice: make restyling of notice boxes more robust [#20](https://github.com/McShelby/hugo-theme-relearn/issues/20) +- [**feature**] notice: fix contrast issues [#19](https://github.com/McShelby/hugo-theme-relearn/issues/19) +- [**feature**] notice: align box colors to common standards [#18](https://github.com/McShelby/hugo-theme-relearn/issues/18) +- [**feature**] notice: use distinct icons for notice box type [#17](https://github.com/McShelby/hugo-theme-relearn/issues/17) + +### Fixes + +- [**bug**] attachments: support i18n for attachment size [#21](https://github.com/McShelby/hugo-theme-relearn/issues/21) +- [**bug**] notice: support i18n for box labels [#16](https://github.com/McShelby/hugo-theme-relearn/issues/16) +- [**bug**] notice: support multiple blocks in one box [#15](https://github.com/McShelby/hugo-theme-relearn/issues/15) + +### Maintenance + +- [**task**] dependency: upgrade jquery to 3.6.0 [#30](https://github.com/McShelby/hugo-theme-relearn/issues/30) + +--- + +## 1.1.1 (2021-07-04) + +### Maintenance + +- [**task**] theme: prepare for new hugo theme registration [#13](https://github.com/McShelby/hugo-theme-relearn/issues/13) + +--- + +## 1.1.0 (2021-07-02) + +### Enhancements + +- [**feature**] mermaid: expose options in config.toml [#4](https://github.com/McShelby/hugo-theme-relearn/issues/4) + +### Fixes + +- [**bug**] mermaid: config option for CDN url not used [#12](https://github.com/McShelby/hugo-theme-relearn/issues/12) +- [**bug**] mermaid: only highlight text in HTML elements [#10](https://github.com/McShelby/hugo-theme-relearn/issues/10) +- [**bug**] mermaid: support pan & zoom for graphs [#9](https://github.com/McShelby/hugo-theme-relearn/issues/9) +- [**bug**] mermaid: code fences not always rendered [#6](https://github.com/McShelby/hugo-theme-relearn/issues/6) +- [**bug**] mermaid: search term on load may bomb chart [#5](https://github.com/McShelby/hugo-theme-relearn/issues/5) + +### Maintenance + +- [**task**] mermaid: update to 8.10.2 [#7](https://github.com/McShelby/hugo-theme-relearn/issues/7) + +--- + +## 1.0.1 (2021-07-01) + +### Maintenance + +- [**task**] Prepare for hugo showcase [#3](https://github.com/McShelby/hugo-theme-relearn/issues/3) + +--- + +## 1.0.0 (2021-07-01) + +### Maintenance + +- [**task**] Fork project [#1](https://github.com/McShelby/hugo-theme-relearn/issues/1) diff --git a/themes/relearn/exampleSite/content/basics/_index.en.md b/themes/relearn/exampleSite/content/basics/_index.en.md new file mode 100755 index 0000000..4d67f9b --- /dev/null +++ b/themes/relearn/exampleSite/content/basics/_index.en.md @@ -0,0 +1,11 @@ ++++ +chapter = true +title = "Basics" +weight = 1 ++++ + +### Chapter 1 + +# Basics + +Discover what this Hugo theme is all about and the core-concepts behind it. diff --git a/themes/relearn/exampleSite/content/basics/_index.pir.md b/themes/relearn/exampleSite/content/basics/_index.pir.md new file mode 100644 index 0000000..3ffb2d4 --- /dev/null +++ b/themes/relearn/exampleSite/content/basics/_index.pir.md @@ -0,0 +1,6 @@ ++++ +chapter = true +title = "Basics" +weight = 1 ++++ +{{< piratify >}} \ No newline at end of file diff --git a/themes/relearn/exampleSite/content/basics/configuration/_index.en.md b/themes/relearn/exampleSite/content/basics/configuration/_index.en.md new file mode 100644 index 0000000..c43c445 --- /dev/null +++ b/themes/relearn/exampleSite/content/basics/configuration/_index.en.md @@ -0,0 +1,160 @@ ++++ +title = "Configuration" +weight = 20 ++++ + +## Global site parameters + +On top of [Hugo global configuration](https://gohugo.io/overview/configuration/), the Relearn theme lets you define the following parameters in your `config.toml` (here, values are default). + +Note that some of these parameters are explained in details in other sections of this documentation. + +```toml +[params] + # This controls whether submenus will be expanded (true), or collapsed (false) in the + # menu; if no setting is given, the first menu level is set to false, all others to true; + # this can be overridden in the pages frontmatter + alwaysopen = true + # Prefix URL to edit current page. Will display an "Edit" button on top right hand corner of every page. + # Useful to give opportunity to people to create merge request for your doc. + # See the config.toml file from this documentation site to have an example. + editURL = "" + # Author of the site, will be used in meta information + author = "" + # Description of the site, will be used in meta information + description = "" + # Shows a checkmark for visited pages on the menu + showVisitedLinks = false + # Disable search function. It will hide search bar + disableSearch = false + # Disable search in hidden pages, otherwise they will be shown in search box + disableSearchHiddenPages = false + # Disables hidden pages from showing up in the sitemap and on Google (et all), otherwise they may be indexed by search engines + disableSeoHiddenPages = false + # Disables hidden pages from showing up on the tags page although the tag term will be displayed even if all pages are hidden + disableTagHiddenPages = false + # Javascript and CSS cache are automatically busted when new version of site is generated. + # Set this to true to disable this behavior (some proxies don't handle well this optimization) + disableAssetsBusting = false + # Set this to true to disable copy-to-clipboard button for inline code. + disableInlineCopyToClipBoard = false + # A title for shortcuts in menu is set by default. Set this to true to disable it. + disableShortcutsTitle = false + # If set to false, a Home button will appear below the search bar on the menu. + # It is redirecting to the landing page of the current language if specified. (Default is "/") + disableLandingPageButton = true + # When using mulitlingual website, disable the switch language button. + disableLanguageSwitchingButton = false + # Hide breadcrumbs in the header and only show the current page title + disableBreadcrumb = true + # If set to true, hide table of contents menu in the header of all pages + disableToc = false + # If set to false, load the Mermaid module on every page regardless if a Mermaid shortcode or Mermaid codefence is present + disableMermaid = false + # Specifies the remote location of the Mermaid js + customMermaidURL = "https://unpkg.com/mermaid/dist/mermaid.min.js" + # Initialization parameter for Mermaid, see Mermaid documentation + mermaidInitialize = "{ \"theme\": \"default\" }" + # If set to false, load the Swagger module on every page regardless if a Swagger shortcode is present + disableSwagger = false + # Specifies the remote location of the RapiDoc js + customSwaggerURL = ""https://unpkg.com/rapidoc/dist/rapidoc-min.js" + # Initialization parameter for Swagger, see RapiDoc documentation + swaggerInitialize = "{ \"theme\": \"light\" }" + # Hide Next and Previous page buttons normally displayed full height beside content + disableNextPrev = true + # Order sections in menu by "weight" or "title". Default to "weight"; + # this can be overridden in the pages frontmatter + ordersectionsby = "weight" + # Change default color scheme with a variant one. Eg. can be "red", "blue", "green" or an array like [ "blue", "green" ]. + themeVariant = "relearn-light" + # Change the title separator. Default to "::". + titleSeparator = "-" + # If set to true, the menu in the sidebar will be displayed in a collapsible tree view. + collapsibleMenu = false +``` + +## A word on running your site in a subfolder + +The theme runs best if your site is installed in the root of your webserver. If your site is served from a subfolder, eg. `https://example.com/mysite/`, you have to set the following lines to your `config.toml` + +````toml +baseURL = "https://example.com/mysite/" +canonifyURLs = true +```` + +Without `canonifyURLs=true` URLs in sublemental pages (like `sitemap.xml`, `rss.xml`) will be generated falsly while your HTML files will still work. See https://github.com/gohugoio/hugo/issues/5226. + +## Activate search + +If not already present, add the follow lines in the same `config.toml` file. + +```toml +[outputs] + home = ["HTML", "RSS", "JSON"] +``` + +Relearn theme uses the last improvement available in hugo version 20+ to generate a json index file ready to be consumed by lunr.js javascript search engine. + +> Hugo generate lunrjs index.json at the root of public folder. +> When you build the site with `hugo server`, hugo generates it internally and of course it doesn’t show up in the filesystem + +## Activate print support + +You can activate print support to add the capability to print whole chapters or even the complete site. Just add the `PRINT` output format to your home, section and page in your `config.toml` as seen below: + +```toml +[outputs] + home = ["HTML", "RSS", "PRINT", "JSON"] + section = ["HTML", "RSS", "PRINT"] + page = ["HTML", "RSS", "PRINT"] +``` + +This will add a little printer icon in the top bar. It will switch the page to print preview when clicked. You can then send this page to the printer by using your browser's usual print functionality. + +{{% notice note %}} +While colors of your chosen color variant are reset to the theme's light standard values for printing, this does not apply for Mermaid diagrams and Swagger/OpenAPI Specification. Those will still use the colors of your chosen color variant which may cause a non coherent look on paper. +{{% /notice %}} + +## Mermaid + +The Mermaid configuration parameters can also be set on a specific page. In this case, the global parameter would be overwritten by the local one. See [Mermaid]({{< relref "shortcodes/mermaid" >}}) for additional documentation. + +> Example: +> +> Mermaid is globally disabled. By default it won't be loaded by any page. +> On page "Architecture" you need a class diagram. You can set the Mermaid parameters locally to only load mermaid on this page (not on the others). + +You also can disable Mermaid for specific pages while globally enabled. + +## Home Button Configuration + +If the `disableLandingPageButton` option is set to `false`, a Home button will appear +on the left menu. It is an alternative for clicking on the logo. To edit the +appearance, you will have to configure two parameters for the defined languages: + +```toml +[Languages] +[Languages.en] +... +landingPageURL = "/" +landingPageName = " Home" +... +[Languages.pir] +... +landingPageURL = "/pir/" +landingPageName = " Arrr! Homme" +... +``` + +If those params are not configured for a specific language, they will get their +default values: + +```toml +landingPageURL = "/" +landingPageName = " Home" +``` + +The home button is going to look like this: + + diff --git a/themes/relearn/exampleSite/content/basics/configuration/_index.pir.md b/themes/relearn/exampleSite/content/basics/configuration/_index.pir.md new file mode 100644 index 0000000..5849920 --- /dev/null +++ b/themes/relearn/exampleSite/content/basics/configuration/_index.pir.md @@ -0,0 +1,5 @@ ++++ +title = "Configurrrat'n" +weight = 20 ++++ +{{< piratify >}} \ No newline at end of file diff --git a/themes/relearn/exampleSite/content/basics/configuration/images/home_button_defaults.png b/themes/relearn/exampleSite/content/basics/configuration/images/home_button_defaults.png new file mode 100644 index 0000000..ef63acb Binary files /dev/null and b/themes/relearn/exampleSite/content/basics/configuration/images/home_button_defaults.png differ diff --git a/themes/relearn/exampleSite/content/basics/customization/_index.en.md b/themes/relearn/exampleSite/content/basics/customization/_index.en.md new file mode 100644 index 0000000..f05ed60 --- /dev/null +++ b/themes/relearn/exampleSite/content/basics/customization/_index.en.md @@ -0,0 +1,81 @@ ++++ +title = "Customization" +weight = 25 ++++ + +The Relearn theme has been built to be as configurable as possible by defining multiple [partials](https://gohugo.io/templates/partials/) + +In `themes/hugo-theme-relearn/layouts/partials/`, you will find all the partials defined for this theme. If you need to overwrite something, don't change the code directly. Instead [follow this page](https://gohugo.io/themes/customizing/). You'd create a new partial in the `layouts/partials` folder of your local project. This partial will have the priority. + +This theme defines the following partials : + +- `header.html`: the header of the page. _Not meant to be overwritten_ +- `footer.html`: the footer of the page._Not meant to be overwritten_ +- `menu.html`: left menu. _Not meant to be overwritten_ +- `search.html`: search box. _Not meant to be overwritten_ +- `custom-header.html`: custom headers in page. Meant to be overwritten when adding CSS imports. Don't forget to include `style` HTML tag directive in your file. +- `custom-footer.html`: custom footer in page. Meant to be overwritten when adding Javacript. Don't forget to include `javascript` HTML tag directive in your file. +- `favicon.html`: the favicon +- `logo.html`: the logo, on top left hand corner +- `meta.html`: HTML meta tags, if you want to change default behavior +- `menu-pre.html`: side-wide configuration to prepend to menu items. If you override this, it is your responsiblity to take the page's `pre` setting into account. +- `menu-post.html`: side-wide configuration to append to menu items. If you override this, it is your responsiblity to take the page's `post` setting into account. +- `menu-footer.html`: footer of the the left menu +- `toc.html`: table of contents +- `content.html`: the content page itself. This can be overridden if you wan't to display page's meta data above or below the content. +- `content-footer`: footer below the content, has a default implementation but you can overwrite it if you don't like it. +## Change the logo + +Create a new file in `layouts/partials/` named `logo.html`. Then write any HTML you want. +You could use an `img` HTML tag and reference an image created under the *static* folder, or you could paste a SVG definition! + +{{% notice note %}} +The size of the logo will adapt automatically +{{% /notice %}} + +## Change the favicon + +If your favicon is a SVG, PNG or ICO, just drop off your image in your local `static/images/` folder and name it `favicon.svg`, `favicon.png` or `favicon.ico` respectivly. + +If no favicon file is found, the theme will lookup the alternative filename `logo` in the same location and will repeat the search for the list of supported file types. + +If you need to change this default behavior, create a new file in `layouts/partials/` named `favicon.html`. Then write something like this: + +```html + +``` + +## Change the colors {#theme-variant} + +The Relearn theme lets you choose between some predefined color variants in light or dark mode, but feel free to add one yourself! + +You can preview the shipped variants by changing them in the variant selector at the bottom of the menu. + +### Single variant + +Set the `themeVariant` value with the name of your theme file. That's it! + +```toml +[params] + themeVariant = "relearn-light" +``` + +In the above exaple your theme file has to be named `theme-relearn-light.css` + +### Multiple variants + +You can also set multiple variants. In this case, the first variant is the default choosen on first view and a variant switch will be shown in the menu footer. + +```toml +[params] + # Change default color scheme with a variant one. + themeVariant = [ "relearn-light", "relearn-dark" ] +``` + +{{% notice tip %}} +If you want to switch the syntax highlightning theme together with your color variant, generate a syntax highlighting stylesheet and configure your installation [according to Hugo's documentation](https://gohugo.io/content-management/syntax-highlighting/), and `@import` this stylesheet in your color variant stylesheet. For an example, take a look into `theme-relearn-light.css` and `config.toml` of the exampleSite. +{{% /notice %}} + +### Roll your own + +If you are not happy with the shipped variants you can either copy one of the shipped files, edit them in a text editor and configure the `themeVariant` parameter in your `config.toml` or just use the [interactive variant generator]({{%relref "basics/generator" %}}). diff --git a/themes/relearn/exampleSite/content/basics/customization/_index.pir.md b/themes/relearn/exampleSite/content/basics/customization/_index.pir.md new file mode 100644 index 0000000..03cd9da --- /dev/null +++ b/themes/relearn/exampleSite/content/basics/customization/_index.pir.md @@ -0,0 +1,5 @@ ++++ +title = "Customizat'n" +weight = 25 ++++ +{{< piratify >}} \ No newline at end of file diff --git a/themes/relearn/exampleSite/content/basics/generator/_index.en.md b/themes/relearn/exampleSite/content/basics/generator/_index.en.md new file mode 100644 index 0000000..af8b3e7 --- /dev/null +++ b/themes/relearn/exampleSite/content/basics/generator/_index.en.md @@ -0,0 +1,37 @@ ++++ +disableMermaid = false +title = "Stylesheet generator" +weight = 26 ++++ + +This interactive tool may help you to generate your own color variant stylesheet. + +To get started, first select a color variant from the variant switch that fits you best as a starting point. + +The graph is interactive and reflect the current colors. You can click on any of the colored boxes to adjust the respective color. The graph and the page will update accordingly. + +The arrowed lines reflects how colors are inherited thru different parts of the theme if the descendent isn't overwritten. If you want to delete a color and let it inherit from its parent, just delete the value from the input field. + +To better understand this select the `neon` variant and modify the differnet heading colors. There, colors for the heading `h2`, `h3` and `h4` are explicitly set. `h5` is not set and inherits its value from `h4`. `h6` is also not set and inherits its value from `h5`. + +Once you've changed a color, the variant switch will show a "My custom variant" entry and your changes are stored in the browser. You can change pages and even close the browser without losing your changes. + +Once you are satisfied, you can download the new variants file and install it in your site. + +{{% notice note %}} +This only works in modern browsers. +{{% /notice %}} + +## Variant generator + + Download variant + Reset variant + +Lorem ipsum dolor sit amet, graecis denique ei vel, at duo primis mandamus. Et legere ocurreret pri, animal tacimates complectitur ad cum. Cu eum inermis inimicus efficiendi. Labore officiis his ex, soluta officiis concludaturque ei qui, vide sensibus vim ad.
+``` + +## Text Markers + +### Bold + +For emphasizing a snippet of text with a heavier font-weight. + +The following snippet of text is **rendered as bold text**. + +```markdown +**rendered as bold text** +``` + +renders to: + + +**rendered as bold text** + + +and this HTML + +```html +rendered as bold text +``` + +### Italics + +For emphasizing a snippet of text with italics. + +The following snippet of text is _rendered as italicized text_. + +```markdown +_rendered as italicized text_ +``` + +renders to: + + +_rendered as italicized text_ + + +and this HTML: + +```html +rendered as italicized text +``` + +### Strikethrough + +In GFM (GitHub flavored Markdown) you can do strikethroughs. + +```markdown +~~Strike through this text.~~ +``` + +Which renders to: + +~~Strike through this text.~~ + +HTML: + +```html +++``` + +Blockquotes can also be nested: + +```markdown +> Donec massa lacus, ultricies a ullamcorper in, fermentum sed augue. Nunc augue augue, aliquam non hendrerit ac, commodo vel nisi. +> +> > Sed adipiscing elit vitae augue consectetur a gravida nunc vehicula. Donec auctor odio non est accumsan facilisis. Aliquam id turpis in dolor tincidunt mollis ac eu diam. +> +> Mauris sit amet ligula egestas, feugiat metus tincidunt, luctus libero. Donec congue finibus tempor. Vestibulum aliquet sollicitudin erat, ut aliquet purus posuere luctus. +``` + +Renders to: + +> Donec massa lacus, ultricies a ullamcorper in, fermentum sed augue. Nunc augue augue, aliquam non hendrerit ac, commodo vel nisi. +> +> > Sed adipiscing elit vitae augue consectetur a gravida nunc vehicula. Donec auctor odio non est accumsan facilisis. Aliquam id turpis in dolor tincidunt mollis ac eu diam. +> +> Mauris sit amet ligula egestas, feugiat metus tincidunt, luctus libero. Donec congue finibus tempor. Vestibulum aliquet sollicitudin erat, ut aliquet purus posuere luctus. + +## Lists + +### Unordered + +A list of items in which the order of the items does not explicitly matter. + +You may use any of the following symbols to denote bullets for each list item: + +```markdown +* valid bullet +- valid bullet ++ valid bullet +``` + +For example + +```markdown ++ Lorem ipsum dolor sit amet ++ Consectetur adipiscing elit ++ Integer molestie lorem at massa ++ Facilisis in pretium nisl aliquet ++ Nulla volutpat aliquam velit + - Phasellus iaculis neque + - Purus sodales ultricies + - Vestibulum laoreet porttitor sem + - Ac tristique libero volutpat at ++ Faucibus porta lacus fringilla vel ++ Aenean sit amet erat nunc ++ Eget porttitor lorem +``` + +Renders to: + + ++ Lorem ipsum dolor sit amet ++ Consectetur adipiscing elit ++ Integer molestie lorem at massa ++ Facilisis in pretium nisl aliquet ++ Nulla volutpat aliquam velit + - Phasellus iaculis neque + - Purus sodales ultricies + - Vestibulum laoreet porttitor sem + - Ac tristique libero volutpat at ++ Faucibus porta lacus fringilla vel ++ Aenean sit amet erat nunc ++ Eget porttitor lorem + + +And this HTML + +```html +Fusion Drive combines a hard drive with a flash storage (solid-state drive) and presents it as a single logical volume with the space of both drives combined.
+
In this example, <div></div> should be wrapped as code.
+
+ // Some comments
+ line 1 of code
+ line 2 of code
+ line 3 of code
+
+
+```
+
+### Block code "fences"
+
+Use "fences" ```` ``` ```` to block in multiple lines of code.
+
+````plaintext
+```
+Sample text here...
+```
+````
+
+HTML:
+
+```html
+
+ Sample text here...
+
+```
+
+### Syntax highlighting
+
+GFM, or "GitHub Flavored Markdown" also supports syntax highlighting. To activate it, usually you simply add the file extension of the language you want to use directly after the first code "fence", ` ```js `, and syntax highlighting will automatically be applied in the rendered HTML.
+
+See [Code Highlighting]({{% relref "syntaxhighlight" %}}) for additional documentation.
+
+For example, to apply syntax highlighting to JavaScript code:
+
+````plaintext
+```js
+grunt.initConfig({
+ assemble: {
+ options: {
+ assets: 'docs/assets',
+ data: 'src/data/*.{json,yml}',
+ helpers: 'src/custom-helpers.js',
+ partials: ['src/partials/**/*.{hbs,md}']
+ },
+ pages: {
+ options: {
+ layout: 'default.hbs'
+ },
+ files: {
+ './': ['src/templates/pages/index.hbs']
+ }
+ }
+ }
+};
+```
+````
+
+Renders to:
+
+```js
+grunt.initConfig({
+ assemble: {
+ options: {
+ assets: 'docs/assets',
+ data: 'src/data/*.{json,yml}',
+ helpers: 'src/custom-helpers.js',
+ partials: ['src/partials/**/*.{hbs,md}']
+ },
+ pages: {
+ options: {
+ layout: 'default.hbs'
+ },
+ files: {
+ './': ['src/templates/pages/index.hbs']
+ }
+ }
+ }
+};
+```
+
+## Tables
+
+Tables are created by adding pipes as dividers between each cell, and by adding a line of dashes (also separated by bars) beneath the header. Note that the pipes do not need to be vertically aligned.
+
+```markdown
+| Option | Description |
+| ------ | ----------- |
+| data | path to data files to supply the data that will be passed into templates. |
+| engine | engine to be used for processing templates. Handlebars is the default. |
+| ext | extension to be used for dest files. |
+```
+
+Renders to:
+
+| Option | Description |
+| ------ | ----------- |
+| data | path to data files to supply the data that will be passed into templates. |
+| engine | engine to be used for processing templates. Handlebars is the default. |
+| ext | extension to be used for dest files. |
+
+And this HTML:
+
+```html
+| Option | +Description | +
|---|---|
| data | +path to data files to supply the data that will be passed into templates. | +
| engine | +engine to be used for processing templates. Handlebars is the default. | +
| ext | +extension to be used for dest files. | +
simple HTML element ?
+
+## Block Code
+
+````
+Code fences without any selected language
+````
+
+````json
+{
+ "well": "some JSON in codefences in here"
+}
+````
+
+{
+ "well": "some JSON in HTML elements here"
+}
++Some preformatted stuff in HTML elements +diff --git a/themes/relearn/exampleSite/content/tests/code/_index.pir.md b/themes/relearn/exampleSite/content/tests/code/_index.pir.md new file mode 100644 index 0000000..3207c19 --- /dev/null +++ b/themes/relearn/exampleSite/content/tests/code/_index.pir.md @@ -0,0 +1,5 @@ ++++ +description = "Some test'n fer different styles used 'n rules highlightn'n an' preformatted blocks" +title = "Code" ++++ +{{< piratify >}} \ No newline at end of file diff --git a/themes/relearn/exampleSite/content/tests/images/_index.en.md b/themes/relearn/exampleSite/content/tests/images/_index.en.md new file mode 100644 index 0000000..bd2d96f --- /dev/null +++ b/themes/relearn/exampleSite/content/tests/images/_index.en.md @@ -0,0 +1,58 @@ ++++ +description = "Some testing for different styles of image links" +title = "Images" ++++ + +Some testing for different styles of image links. + +## Markdown + +### Relative to page + + + +### Relative to page up level + + + +### Static + + + +### External fully qualified + + + +### External without scheme + + + +### External without scheme and scheme separator + + + +## HTML + +### Relative to page + +
Built with by Hugo
+ \ No newline at end of file diff --git a/themes/relearn/exampleSite/layouts/partials/menu-pre.html b/themes/relearn/exampleSite/layouts/partials/menu-pre.html new file mode 100644 index 0000000..98b2be8 --- /dev/null +++ b/themes/relearn/exampleSite/layouts/partials/menu-pre.html @@ -0,0 +1 @@ +{{ if .Params.chapter }}{{ .Params.weight }}. {{ end }} \ No newline at end of file diff --git a/themes/relearn/exampleSite/layouts/shortcodes/ghcontributors.html b/themes/relearn/exampleSite/layouts/shortcodes/ghcontributors.html new file mode 100644 index 0000000..3e8a928 --- /dev/null +++ b/themes/relearn/exampleSite/layouts/shortcodes/ghcontributors.html @@ -0,0 +1,31 @@ + +Fello' pirrates, be awarrre some featurrres may not work fer us in this trrranslat'n. Like table of rrramblings, some Merrrmaids and stuff.
++ The site is working. Don't forget to customize this page with your own. You typically have 3 choices : +
+