Written some text

This commit is contained in:
Eduardo Cueto Mendoza 2020-06-13 23:48:49 -06:00
parent 524dda88de
commit 538642b269
2 changed files with 1 additions and 120 deletions

View File

@ -1,55 +0,0 @@
@def hascode = true
# FAQ - Troubleshooting
This page is about some of the known errors you may encounter when using Franklin and how to deal with them.
If you encounter an error that is not mentioned here, then it's probably a bug and it would be great if you could open an issue!
\toc
## Error on interruption
You may (rarely) get an an error thrown at you when interrupting the server with `<CTRL>+C`, particularly when using Juno.
There are a couple of reasons this may happen, both unrelated to Franklin.
### Juno
Juno (very rarely) crashes if you coincidentally press `<CTRL>+C` while Juno is doing something in the background (Juno issue [#309](https://github.com/JunoLab/Juno.jl/issues/309)).
The stacktrace you will see will seem particularly obscure, for instance:
```
InterruptException:
_string_n at string.jl:60 [inlined]
StringVector at iobuffer.jl:31 [inlined]
#IOBuffer#320(::Bool, ::Bool, ::Nothing, ::Bool, ::Int64, ::Int64, ::Type{Base.GenericIOBuffer{Array{UInt8,1}}}) at iobuffer.jl:114
(...)
```
or
```
julia> "miniERROR: InterruptException:
Stacktrace:
[1] poptaskref(::Base.InvasiveLinkedListSynchronized{Task}) at ./task.jl:564
[2] wait() at ./task.jl:591
(...)
```
**Solution**: ignore the error, kill then restart the server or, failing that, kill and restart Julia.
### Not-Juno
The [`LiveServer.jl`](https://github.com/asprionj/LiveServer.jl) package, which handles the live-serving of the files, is based upon [`HTTP.jl`](https://github.com/asprionj/LiveServer.jl).
The latter has a fairly complex codebase with a number of asynchronous tasks and is known to sometimes crash in (somewhat) mysterious ways.
If the stacktrace mentions `uv_write`, `uv_write_async`, `libuv` or something of the sorts, then this is an example of _known but mysterious way_.
Like the "Juno" case, these errors are caused when you happen to press interrupt just as the package was doing something important in the background.
This is very rare but can happen and you can safely ignore it.
**Solution**: ignore the error, kill then restart the server or, failing that, kill and restart Julia.
## IOStream error
See the comment about HTTP.jl in the [subsection above](#Not-Juno-1).

View File

@ -31,67 +31,3 @@ end
## A bit about myself
My interest in science started from a very early age I was in love with physics because a teacher in elementary school had a copy of the book `COSMOS` which he lend me and I was marveled by the words of [Carl Sagan](https://en.wikipedia.org/wiki/Carl_Sagan)
<!--
# Building static websites in Julia
\blurb{Franklin is a simple, customisable static site generator oriented towards technical blogging and light, fast-loading pages.}
## Key features
@@flist
* \goto{/syntax/markdown/} Augmented markdown allowing definition of LaTeX-like commands,
* \goto{/syntax/divs-commands/} Easy inclusion of user-defined div-blocks,
* \goto{/syntax/divs-commands/} Maths rendered via [KaTeX](https://katex.org/), code via [highlight.js](https://highlightjs.org) both can be pre-rendered,
* \goto{/code/} Can live-evaluate Julia code blocks,
* \goto{/workflow/#creating_your_website} Live preview of modifications,
* \goto{/workflow/#optimisation_step} Simple optimisation step to compress and pre-render the website,
* \goto{/workflow/#publication_step} Simple publication step to deploy the website,
* \goto{/code/literate/} Straightforward integration with [Literate.jl](https://github.com/fredrikekre/Literate.jl).
@@
## Quick start
To install Franklin with Julia **≥ 1.3**,
```julia-repl
(v1.4) pkg> add Franklin
```
You can then just try it out:
```julia-repl
julia> using Franklin
julia> newsite("mySite", template="pure-sm")
✓ Website folder generated at "mySite" (now the current directory).
→ Use serve() from Franklin to see the website in your browser.
julia> serve()
→ Initial full pass...
→ Starting the server...
✓ LiveServer listening on http://localhost:8000/ ...
(use CTRL+C to shut down)
```
If you navigate to that URL in your browser, you will see the website. If you then open `index.md` in an editor and modify it at will, the changes will be live rendered in your browser.
You can also inspect the file `menu1.md` which offers more examples of what Franklin can do.
## Installing optional extras
Franklin allows a post-processing step to compress HTML and CSS and pre-render code blocks and math environments.
This requires a couple of dependencies:
@@tlist
* [`python3`](https://www.python.org/downloads/) for the minification of the site,
* [`node.js`](https://nodejs.org/en/) for the pre-rendering of KaTeX and code highlighting.
@@
You will then need to install `highlight.js`, which you should do from Julia using the [NodeJS.jl](https://github.com/davidanthoff/NodeJS.jl) package:
```julia-repl
julia> using NodeJS
julia> run(`sudo $(npm_cmd()) install highlight.js`)
```
**Note**: a key advantage of using `NodeJS` for this instead of using `npm` yourself is that it puts the libraries in the "right place" for Julia to find them.
Assuming you have `python3`, Franklin will try to install the python package [`css_html_js_minify`](https://github.com/juancarlospaco/css-html-js-minify) if via `pip3`.
-->