[v3] Update Markdown files to latest spec (#599)

concepts/access-behaviour/about.md

@@ -1,3 +1,5 @@
+# About
+
 Elixir uses [_Behaviours_][behaviours] to provide common generic interfaces while facilitating specific implementations for each module which implements the behaviour. One of those behaviours is the _Access Behaviour_.
 
 The _Access Behaviour_ provides a common interface for retrieving key-based data from a data structure. It is implemented for maps and keyword lists.

concepts/access-behaviour/introduction.md

@@ -1,3 +1,5 @@
+# Introduction
+
 Elixir uses code _Behaviours_ to provide common generic interfaces while facilitating specific implementations for each module which implements it. One such common example is the _Access Behaviour_.
 
 The _Access Behaviour_ provides a common interface for retrieving data from a key-based data structure. The _Access Behaviour_ is implemented for maps and keyword lists, but let's look at its use for maps to get a feel for it. _Access Behaviour_ specifies that when you have a map, you may follow it with _square brackets_ and then use the key to retrieve the value associated with that key.

concepts/agent/about.md

@@ -1,3 +1,5 @@
+# About
+
 While spawning a process is easy, managing its state and behavior can become very complicated. The [`Agent`][agent-module] module is an abstraction to facilitate managing a shared state in an Elixir process.
 
 When using `Agent` module functions it is customary to encapsulate the agent-related functions in a single module.

concepts/agent/introduction.md

@@ -1,3 +1,5 @@
+# Introduction
+
 The `Agent` module facilitates an abstraction for spawning processes and the _receive-send_ loop. From here, we will call processes started using the `Agent` module _'agent processes'_. An _agent process_ might be chosen to represent a central shared state.
 
 To start an _agent process_, `Agent` provides the `start/2` function. The supplied function when `start`_-ing_ the _agent process_ returns the initial state of the process:

concepts/anonymous-functions/about.md

@@ -1,3 +1,5 @@
+# About
+
 [Anonymous functions][anon-fns] are commonly used throughout Elixir on their own, as return values, and as arguments in higher order functions such as `Enum.map/2`:
 
 ```elixir

concepts/anonymous-functions/introduction.md

@@ -1,3 +1,5 @@
+# Introduction
+
 Functions are treated as first class citizens in Elixir. This means functions:
 
 - Can be assigned to variables.

concepts/atoms/about.md

@@ -1,3 +1,5 @@
+# About
+
 You can use [atoms][atom] whenever you have a set of constants to express. Atoms provide a type-safe way to compare values. An atom is defined by its name, prefixed by a colon:
 
 ```elixir

concepts/atoms/introduction.md

@@ -1,3 +1,5 @@
+# Introduction
+
 Elixir's `atom` type represents a fixed constant. An atom's value is simply its own name. This gives us a type-safe way to interact with data. Atoms can be defined as follows:
 
 ```elixir

concepts/basics/about.md

@@ -1,3 +1,5 @@
+# About
+
 - Elixir is dynamically-typed.
   - The type of a variable is only checked at run-time.
 - Using the match [`=`][match] operator, we can bind a value of any type to a variable name:

concepts/basics/introduction.md

@@ -1,3 +1,5 @@
+# Introduction
+
 Elixir is a dynamically-typed language, meaning that the type of a variable is only checked at runtime. Using the match `=` operator, we can bind a value of any type to a variable name:
 
 ```elixir
@@ -9,7 +11,7 @@ count = false # You may re-bind any type to a variable
 message = "Success!" # Strings can be created by enclosing characters within double quotes
 ```
 
-### Modules
+## Modules
 
 Elixir is an [functional-programming language][functional-programming] and requires all named functions to be defined in a _module_. The `defmodule` keyword is used to define a module. All modules are available to all other modules at runtime and do not require an _access modifier_ to make them visible to other parts of the program. A _module_ is analogous to a _class_ in other programming languages.
 
@@ -19,7 +21,7 @@ defmodule Calculator do
 end
 ```
 
-### Named functions
+## Named functions
 
 _Named Functions_ must be defined in a module. Each function can have zero or more arguments. All arguments are dynamically-typed, and the return type is not explicitly declared, it is the type of the value returned. An _access modifier_ can be specified for functions, making only desired functions available for use external to the module. In a function, the value of the last expression is _implicitly returned_ to the calling function.
 
@@ -42,7 +44,7 @@ sum = Calculator.short_add(2, 2)
 # => 4
 ```
 
-### Arity of functions
+## Arity of functions
 
 It is common to refer to functions with their _arity_. The _arity_ of a function is the number of arguments it accepts.
 
@@ -53,15 +55,15 @@ def add(x, y, z) do
 end
 ```
 
-### Standard library
+## Standard library
 
 Elixir has a very rich and well-documented standard library. The documentation is available online at [hexdocs.pm/elixir][docs]. Save this link somewhere - you will use it a lot!
 
 Most built-in data types have a corresponding module that offers functions for working with that data type, e.g. there's the `Integer` module for integers, `String` module for strings, `List` module for lists and so on.
 
 A notable module is the `Kernel` module. It provides the basic capabilities on top of which the rest of the standard library is built, like arithmetic operators, control-flow macros, and much more. Functions for the `Kernel` module are automatically imported, so you can use them without the `Kernel.` prefix.
 
-### Documentation
+## Documentation
 
 Documentation is a priority in high-quality Elixir code bases, and there are 3 ways to write inline documentation:
 

concepts/binaries/about.md

@@ -1,3 +1,5 @@
+# About
+
 - The [binary][binary] type is a specialization of the [bitstring][bitstring] type.
 - Binaries are made up of [bytes][wiki-byte].
   - Bytes are 8 [bits][wiki-bit].

concepts/binaries/introduction.md

@@ -1,3 +1,5 @@
+# Introduction
+
 Elixir provides an elegant syntax for working with binary data as we have seen with the `<<>>` special form provided for working with _bitstrings_.
 
 The binary type is a specialization on the bitstring type. Where bitstrings could be of any length (any number of [bits][wiki-bit]), binaries are where the number of bits can be evenly divided by 8. That is, when working with binaries, we often think of things in terms of [bytes][wiki-byte] (8 bits). A byte can represent integer numbers from `0` to `255`. It is common to work with byte values in [hexadecimal][wiki-hexadecimal], `0x00 - 0xFF`.
@@ -12,7 +14,7 @@ Binary literals are defined using the bitstring special form `<<>>`. When defini
 
 A _null-byte_ is another name for `<<0>>`.
 
-### Pattern matching on binary data
+## Pattern matching on binary data
 
 Pattern matching is even extended to binaries, and we can pattern match on a portion of binary data much like we could for a list.
 

concepts/bit-manipulation/about.md

@@ -1,3 +1,5 @@
+# About
+
 [Bitwise binary functions][bitwise-wiki] can be performed on integers using functions from the [Bitwise module][bitwise-hexdocs].
 
 - [`&&&/2`][bitwise-and]: bitwise AND

concepts/bit-manipulation/introduction.md

@@ -1,3 +1,5 @@
+# Introduction
+
 Elixir supports many functions for working with bits found in the _Bitwise module_.
 
 - `&&&/2`: bitwise AND

concepts/bitstrings/about.md

@@ -1,3 +1,5 @@
+# About
+
 [Bitstrings][bitstring] allow programmers to work with binary data effectively.
 
 - You can construct bitstrings elegantly using the [`<<>>` special form][bitstring-form].

concepts/bitstrings/introduction.md

@@ -1,3 +1,5 @@
+# Introduction
+
 Working with binary data is an important concept in any language, and Elixir provides an elegant syntax to write, match, and construct binary data.
 
 In Elixir, binary data is referred to as the bitstring type. The binary data *type* (not to be confused with binary data in general) is a specific form of a bitstring, which we will discuss in a later exercise.
@@ -27,7 +29,7 @@ By default, bitstrings are displayed in chunks of 8 bits (a byte).
 # => <<251, 3::size(3)>>
 ```
 
-### Constructing
+## Constructing
 
 We can combine bitstrings stored in variables using the special form:
 
@@ -38,7 +40,7 @@ combined = <<first::bitstring, second::bitstring>>
 # => <<49::size(6)>>
 ```
 
-### Pattern matching
+## Pattern matching
 
 Pattern matching can also be done to obtain the value from within the special form:
 

concepts/booleans/about.md

@@ -1,3 +1,5 @@
+# About
+
 Elixir represents true and false values with the boolean type. There are only two values: `true` and `false`. These values can be combined with boolean operators ([`and/2`][strict-and], [`or/2`][strict-or], [`not/1`][strict-not]):
 
 ```elixir

concepts/booleans/introduction.md

@@ -1,3 +1,5 @@
+# Introduction
+
 Elixir represents true and false values with the boolean type. There are only two values: `true` and `false`.
 
 ```elixir

concepts/case/about.md

@@ -1,3 +1,5 @@
+# About
+
 [`case`][case] is a control flow structure that allows us to compare a given value against many patterns. Clauses in a `case` expression are evaluated from top to bottom, until a match is found.
 
 In many cases, using `case` is interchangeable with defining multiple function clauses. Pattern matching and guards can be used in `case` clauses.

concepts/case/introduction.md

@@ -1,3 +1,5 @@
+# Introduction
+
 `case` is a control flow structure that allows us to compare a given value against many patterns. Clauses in a `case` statement are evaluated from top to bottom, until a match is found.
 
 ```elixir

concepts/charlists/about.md

@@ -1,3 +1,5 @@
+# About
+
 Charlists are created using single quotes.
 
 ```elixir

concepts/charlists/introduction.md

@@ -1,3 +1,5 @@
+# Introduction
+
 Charlists are created using single quotes.
 
 ```elixir

concepts/closures/about.md

@@ -1,3 +1,5 @@
+# About
+
 Anonymous functions in Elixir are [closures][closure]. They can access variables that are in scope when the function is defined.
 
 ```elixir

concepts/closures/introduction.md

@@ -1,3 +1,5 @@
+# Introduction
+
 Anonymous functions in Elixir are [closures][closure]. They can access variables that are in scope when the function is defined.
 
 ```elixir

concepts/cond/about.md

@@ -1,3 +1,5 @@
+# About
+
 When we want to have branching code, we can use [`cond/1`][cond]:
 
 ```elixir

concepts/cond/introduction.md

@@ -1,3 +1,5 @@
+# Introduction
+
 Often, we want to write code that can branch based on a condition. While there are many ways to do this in Elixir, one of the simplest ways is using `cond/1`.
 
 At its simplest, `cond` follows the first path that evaluates to `true` with one or more branches:

concepts/default-arguments/about.md

@@ -1,3 +1,5 @@
+# About
+
 Functions may declare [default values][default-arguments] for one or more arguments.
 
 ```elixir

concepts/default-arguments/introduction.md

@@ -1,3 +1,5 @@
+# Introduction
+
 Functions may declare default values for one or more arguments. Let's consider this function:
 
 ```elixir

concepts/dynamic-dispatch/about.md

@@ -1,3 +1,5 @@
+# About
+
 Functions in Elixir can be dispatched dynamically.
 
 All module names are atoms. All Elixir module names are automatically prefixed with `Elixir.` when compiled.

concepts/dynamic-dispatch/introduction.md

@@ -1,3 +1,5 @@
+# Introduction
+
 When Elixir resolves the function to be invoked, it uses the Module's name to perform a lookup. The lookup can be done dynamically if the Module's name is bound to a variable.
 
 ```elixir

concepts/enum/about.md

@@ -1,3 +1,5 @@
+# About
+
 `Enum` is a very useful module that provides a set of algorithms for working with enumerables. It offers:
 
 - sorting ([`sort/2`][enum-sort/2], [`sort_by/2`][enum-sort_by/2]),

concepts/enum/introduction.md

@@ -1,3 +1,5 @@
+# Introduction
+
 `Enum` is a very useful module that provides a set of algorithms for working with enumerables. It offers sorting, filtering, grouping, counting, searching, finding min/max values, and much more.
 
 In general, an _enumerable_ is any data that can be iterated over, a collection. In Elixir, an enumerable is any data type that implements the `Enumerable` protocol. The most common of those are lists and maps.

concepts/erlang-libraries/about.md

@@ -1,3 +1,5 @@
+# About
+
 Elixir code runs in the [BEAM virtual machine][beam]. BEAM is part of the [Erlang][erlang] Run-Time System. Being inspired by Erlang, and sharing its run environment, Elixir provides great interoperability with Erlang libraries. This means that Elixir developers can use Erlang libraries from within their Elixir code. In fact, writing Elixir libraries for functionality already provided by Erlang libraries is discouraged in the Elixir community.
 
 As a result, certain functionality, like mathematical operations or timer functions, is only available in Elixir via Erlang.

concepts/erlang-libraries/introduction.md

@@ -1,3 +1,5 @@
+# Introduction
+
 Elixir code runs in the BEAM virtual machine. BEAM is part of the Erlang Run-Time System. Being inspired by Erlang, and sharing its run environment, Elixir provides great interoperability with Erlang libraries. This means that Elixir developers can use Erlang libraries from within their Elixir code. In fact, writing Elixir libraries for functionality already provided by Erlang libraries is discouraged in the Elixir community.
 
 As a result, certain functionality, like mathematical operations or timer functions, is only available in Elixir via Erlang.

concepts/errors/about.md

@@ -1,3 +1,5 @@
+# About
+
 While Elixir programmers often say ["let it crash"][let-it-crash] and code for the ["happy path"][happy-path], there are often times we need to rescue the function call to return a specific value, message or release system resources.
 
 - Functions that raise errors under normal circumstances should have `!` at the end of their name.

concepts/errors/introduction.md

@@ -1,3 +1,5 @@
+# Introduction
+
 Errors happen. In Elixir, while people often say to "let it crash", there are times when we need to rescue the function call to a known good state to fulfil a software contract. In some languages, errors are used as method of control flow, but in Elixir, this pattern is discouraged. We can often recognize functions that may raise an error just by their name: functions that raise errors are to have `!` at the end of their name. This is in comparison with functions that return `{:ok, value}` or `:error`. Look at these library examples:
 
 ```elixir

concepts/exceptions/about.md

@@ -1,3 +1,5 @@
+# About
+
 The [_Exception Behaviour_][exception-behaviour] defines how [`errors`][getting-started-errors] are raised and displayed.
 
 It includes two optional callbacks:

concepts/exceptions/introduction.md

@@ -1,3 +1,5 @@
+# Introduction
+
 All errors in Elixir implement the _Exception Behaviour_. Just like the _Access Behaviour_, the _Exception Behaviour_ defines callback functions that a module must implement to fulfill the software contract of the behaviour. Once an error is defined, it has the following properties:
 
 - The module's name defines the error's name.
@@ -7,7 +9,7 @@ All errors in Elixir implement the _Exception Behaviour_. Just like the _Access
 
 The _Exception Behaviour_ also specifies two callbacks: `message/1` and `exception/1`. If unimplemented, default implementations will be used. `message/1` transforms the error-struct to a readable message when called with `raise`. `exception/1` allows additional context to be added to the message when it is called with `raise/2`
 
-### Defining an exception
+## Defining an exception
 
 To define an exception from an error module, we use the `defexception` macro:
 
@@ -33,7 +35,7 @@ defmodule MyCustomizedError do
 end
 ```
 
-### Using exceptions
+## Using exceptions
 
 Defined errors may be used like a built in error using either `raise/1` or `raise/2`.
 

concepts/file/about.md

@@ -1,3 +1,5 @@
+# About
+
 Functions for working with files are provided by the [`File`][file] module.
 
 To read a whole file, use [`File.read/1`][file-read]. To write to a file, use [`File.write/2`][file-write].

concepts/file/introduction.md

@@ -1,3 +1,5 @@
+# Introduction
+
 Functions for working with files are provided by the `File` module.
 
 To read a whole file, use `File.read/1`. To write to a file, use `File.write/2`.

concepts/floating-point-numbers/about.md

@@ -1,3 +1,5 @@
+# About
+
 There are two different kinds of numbers in Elixir - integers and floats.
 
 Floats are numbers with one or more digits behind the decimal separator. They use the 64-bit double precision floating-point format.

concepts/floating-point-numbers/introduction.md

@@ -1,15 +1,17 @@
+# Introduction
+
 Floats are numbers with one or more digits behind the decimal separator. They use the 64-bit double precision floating-point format.
 
 ```elixir
 float = 3.45
 # => 3.45
 ```
 
-### Working with numbers
+## Working with numbers
 
 In the [`Integer`][integer-functions] and [`Float`][float-functions] modules you can find some useful functions for working with those types. Basic arithmetic operators are defined in the [`Kernel`][kernel-arithmetic-operators] module.
 
-### Conversion
+## Conversion
 
 Integers and floats can be mixed together in a single arithmetic expression. Using a float in an expression ensures the result will be a float too.
 

concepts/guards/about.md

@@ -1,3 +1,5 @@
+# About
+
 [Guards][guards] are used as a complement to pattern matching. They allow for more complex checks. They can be used in [some, but not all situations][where-guards-can-be-used] where pattern matching can be used, for example in function clauses or case clauses.
 
 ```elixir

concepts/guards/introduction.md

@@ -1,3 +1,5 @@
+# Introduction
+
 Guards are used to prevent Elixir from invoking functions based on evaluation of the arguments by guard functions. Guards begin with the `when` keyword, followed by a boolean expression. Guard functions are special functions which:
 
 - Must be pure and not mutate any global states.

concepts/if/about.md

@@ -1,3 +1,5 @@
+# About
+
 Besides `cond`, Elixir also provides the macros [`if/2` and `unless/2`][getting-started-if-unless] which are useful when you need to check for only one condition.
 
 [`if/2`][kernel-if] accepts a condition and two options. It returns the first option if the condition is _truthy_, and the second option if the condition is _falsy_. [`unless/2`][kernel-unless] does the opposite.

concepts/if/introduction.md

@@ -1,3 +1,5 @@
+# Introduction
+
 Besides `cond`, Elixir also provides the macro [`if/2`][getting-started-if-unless] which is useful when you need to check for only one condition.
 
 [`if/2`][kernel-if] accepts a condition and two options. It returns the first option if the condition is _truthy_, and the second option if the condition is _falsy_.
@@ -22,7 +24,7 @@ if age > 16, do: "beer", else: "no beer"
 
 This syntax is helpful for very short expressions, but should be avoided if the expression won't fit on a single line.
 
-### _Truthy_ and _falsy_
+## _Truthy_ and _falsy_
 
 In Elixir, all datatypes evaluate to a _truthy_ or _falsy_ value when they are encountered in a boolean context (like an `if` expression). All data is considered _truthy_ **except** for _false_ and _nil_.
 

concepts/integers/about.md

@@ -1,3 +1,5 @@
+# About
+
 There are two different kinds of numbers in Elixir - integers and floats.
 
 Integers are whole numbers.