tlienart
commented
3 years ago I should probably add a note in the docs on how to do this. The rough steps are as follows:
- porting the design (adjusting the
_layoutand adding the correct javascript and css in_libsand_css) - migrating the content (mostly copy pasting, possibly commenting out Jekyll specific front matter)
- adjusting page aggregation (e.g. "latest blog posts" or "tags") possibly via hfuns
Porting the design
This is usually what takes the most time depending on how complex the website is as CSS and HTML can often be a bit finicky.
Usually there's two layouts to port (one when you're lucky): (1) the landing page and (2) the blog post pages. The procedure is identical and the main idea is to identify the repeated design elements in those pages and put those in the relevant _layout/* files.
To begin with the cover page
- create a site with
Franklin.newsite("name-of-new-site"), this uses the "basic" layout which we'll completely replace - keep the
index.mdfile, possibly simplify its content to just have a title and some text. - look at the HTML of the landing page of the site you want to migrate
- copy paste everything above
<body>in_layout/head. You might want to keep a few things from the default (e.g. the insert of katex/highlight) - copy paste everything below
</body>as well as the loaders for javascript etc in_layout/foot(again you might want to keep a few things) - if there's a footer, copy paste the content in
_layout/page_foot
- copy paste everything above
- copy paste the CSS that's loaded on that page into
_css/and make sure the import statements in thehead.htmlare now/css/thecss.css - copy paste the javascript to
_libs(if you want to serve it, if it's a CDN or whatever, keep as is) - test the website, inevitably here there's a bunch of things that will go wrong. Assuming it didn't just fail, go to
__site/index.htmland look at the produced HTML there, compare it with the desired HTML; adjust things so that these two converge eventually
That's basically it, same procedure for the posts page. If you want to load different blocks of layout for some pages, just use {{ispage /index.html}} ... {{end}} or {{isnotpage ...}} ... {{end}} etc.
One note: by default a Franklin page will look like this:
<!-- usual top stuff doctype etc, head -->
<body>
<div class="franklin-content">
<!-- here all the content transformed from the source markdown -->
<!-- here whatever is in page_foot -->
</div>
<!-- here whatever is in foot -->
</body>
</html>if you do not want the content to be wrapped in a div with class franklin-content (this would be the case for instance if you're using bootstrap), then you can disable this by putting the following in your config.md:
+++
content_tag = ""
+++the content_tag = "" will disable the wrapping into a <div class="franklin-content"> and you can do this wrapping manually into whatever div you want or a <main> or whatever by putting that explicitly in your _layout/head
Migrating content
This is an easy step. Usually most of it can just be copy pasted. The only thing is that if there's Jekyll specific commands (e.g. front matter or whatever) used in those pages, it should be commented out for now and replaced by something Franklin-admissible later.
Aggregation
This will depend on the scenario. The most standard one is to have a list of either all blogposts in chronological order or the x-most recent blogposts, possibly paginated. The pagination can be handled by Franklin, so the main thing to consider is to generate a list and you could do this many ways, as long as it can easily be coded in Julia, you're fine. An example for this is the one used for the Julia website blog:
I hope this kind of makes sense, ping me from one of these repos when you have questions and I'll eventually put stuff together into a doc page
logankilpatrick
Hey @tlienart are there any specific steps or the like that one would take to migrate from Jekyll (for example) to Franklin? I have some websites I want to help move over but don't want to start down the wrong path.