Documentation
getting started with unhack
- Before you begin
- Tutorials
- Creating a Project
- Opening a Project
- The Menubar
- The Sidebar
- Dashboard
- Configuration
- Posts and Pages
- Navigation
- Theme Options
- Publication Settings
- Publishing / Upload
- Preview Changes/Localhost
Before you begin
unHack Beta unfortunately is not able to install all of the dependencies automatically. This article covers all of the things you need to install to ensure unHack runs mostly problem-free.
What do I need to install?
jekyll
unHack requires you to have jekyll installed. Please follow the jekyll Installation Guide if you don’t know how to achieve that.
Caution for Windows Users: If you are using a jekyll installation within the Linux Subsystem of Windows, unHack will not be able to process. Make sure you install jekyll on the regular Windows system.
Git
In order for unHack to publish to GitHub, you need to have Git installed. Git Installation Guide. unHack does not need to publish via GitHub, you can easily publish via FTP, without a Git Installation.
unHack
Obviously, all you need to to is go to the Download Page and then run the executable file.
Tutorials
Please also check the Tutorials Index for some usage examples.
Creating a Project
There are a multitude of ways on how to create a new project.
If you’ve never opened a project before, you’ll be greeted with the Drag-Area Screen that features a Button to create a New Project. You can also access the Creation-Popup via the Menu, or using the Shortcut Ctrl+N or Cmd+N on Windows and Mac respectively.
This will open a popup. As of right now, the only way to create a new jekyll site is using the jekyll new command from within jekyll itself.
Choose a parent directory (unHack will create a new folder for your jekyll site, using the provided project name in this directory). Give the Project a name (this follows the general folder naming rules) and then hit the button to create a new site with jekyll.
Opening a Project
in order for the App to recognize a jekyll site via the Open Command, you need to create a file called unhack.json in the root of the directory. Minimal Requirements for content are:
{
"name": "YOUR SITES NAME HERE"
}
If the site was created using unHack this file has automatically been added.
To Open a Project, you can either drag the folder into the Welcome Screen, or use the Menu Item, or the Shortcut Ctrl+O, and Cmd+O depending on your platform.
The Menubar
unHack comes with a Menu-Bar that has all of the most important Actions and Elements.
File
The File menu is the place for project Management. Here you can open projects or create new ones, and also open the currently active project in the Explorer/Finder to manage the files more traditionally.
Actions
In the Actions tab you can toggle the Publication Settings and upload your site using the chosen publication method.
View
In the View Menu you can enable unHack Dark mode, toggle full screen mode or play with zoom factors if you don’t like the size of things.
Help
The Help Menu will give you access to the App Documentation.
Dev
Since unHack is currently still in Beta, it might be, that you run into a bug. If you feel like something is wrong, you can display the developer tools, which will log error messages. This will be useful for a Developer to Debug. If you are finding an error message, Open an Issue on GitHub.
This is also the place where you can reset all of the stored App Settings (like currently active project, stored screen size or UI Skin). This is only necessary if you run into an issue, and want to try if it gets fixed with a reset.
The Sidebar
On the right, you can see the Sidebar which is the main navigation area.
Dashboard
The Dashboard is the Start Screen, it will give you quick access to the Documentation, and Settings, as well as allow you to create a new Page or Post right from it.
Configuration
In the Configuration View you will find all the Elements from the jekyll _config.yml file. Most of the time the only changes necessary here are Site Title, User Email, Site URL and maybe baseurl. Sometimes the theme will include specific elements, like Social Media Links. This will vary from theme to theme. As of right now, there is no option within unHack to add entries to config, just to modify it. If you want to add additional elements, you need to use a text editor.
Posts and Pages
The Posts and Pages Areas is probably where you will be spending most of your time. It starts with a table, where all of the currently available Posts and Pages are displayed. Drafts and published Files. In this view, you do get quick actions, like Duplicate, and Delete, as well as the option to edit or create a new Entry
Quick Actions
Delete
The Delete Button, will move the file to the Recycle Bin, after you confirm.
Duplicate
The Duplicate Button will create a copy of the file. You can distinguish the copy from the Original via the file name.
Editor
If you edit or create a new entry, you’ll be seeing the Editor View. The Content features a WYSIWYG Markdown Editor, which allows you to write content and directly see what it looks like. In this view you have the option to cancel, save and publish or save as a draft.
Front Matter
The Editor also features a form-like styling for the Front Matter. If a theme does not offer Front Matter configuration in its configuration file, all of the found Front Matter in the Editor will be available as Text-Inputs.
However, unHack offers great Customization Options for all kinds of Front Matter Content Types. More on how this is set Up, can be found in the unHack Theming Guidelines.
Navigation
Navigation is one of the Features only available to themes supporting it. Refer to the Tutorial on how to Build a Menu.
Theme Options
Theme Options is also one of the Features only working with themes supporting it. This is where you can customize the look of a theme.
Publication Settings
Publication Settings is where you set up all of your publication information. The currently active Tab is the Method that will be used for Upload.
FTP
FTP settings will be stored in the Config File. If you are going to upload a project to GitHub after you uploaded it via FTP I strongly recommend putting the configuration File in your gitignore. The Password will not be stored in the Config-File, it will be stored within the App storage. If you want to change a password, just rewrite it into the Form.
GitHub
GitHub Publication currently only works with a working ssh key. There are certain things that need to be ensured before publishing via FTP, please check the Tutorial.
Publishing / Upload
Once you are ready to Upload, hit the Upload Button in the Menu or the Dahsboard. The site will be generated using jekyll and then you will be prompted to upload using the Upload Button.
FTP Upload will overwrite all existing files in that directory, so please make sure you have a backup or are certain that you want your changes on the internet.
GitHub will publish on two branches. Branch one is called Source, it contains all of the source files. then if you are publishing to a user repository it will put all contents of _site into the master branch, and on other repositories into the gh-pages branch. If you don’t have a custom Domain, make sure that you do set baseurl to the name of your repository in your configuration.
Preview Changes/Localhost
As of right now, the Beta Version of unHack does not contain the option to run a localhost, because the process would not die and survived the closing of the App. So if you want to preview your website, you need to go via Terminal.
Navigate into your folder and then run command
jekyll serve
You’ll then be able to preview your site in a browser at localhost:4000. To end the live preview, enter Ctrl+C in the terminal or close it.